はじめに
DBマイグレーションの概要
DBマイグレーション入門
繰り返し可能なマイグレーション
@View、extra-ddl.xml、および繰り返し可能なマイグレーションの使用概要
DBマイグレーションは、エンティティBeanモデルからDDLを生成する機能であり、以前のバージョンのモデルとの差分を判別し、モデルの差異に基づいて適切なDDL変更を生成することをサポートします。
FlywayDb、LiquiBase、または類似のツールを使用して、差分DDLを実行することが想定されています。将来的には、Ebeanは既にほとんどの機能を備えているため、DDLを実行するための組み込みサポートを提供し、開発者のワークフローとDDLスクリプトの順序付けに関する現在の問題に対処できる可能性があります。
DBマイグレーションには2つの出力ファイルがあります
- マイグレーションモデルXML - これは、モデルの論理的な差分を
適用またはpendingDrops変更セットとして表したものです - 適用SQL - これは、適用される変更のDDLスクリプトです
DbMigrationが実行されると、以前のマイグレーションXMLがロードされ、それらが組み合わされて以前のモデルが定義され、既存のエンティティBeanと比較されます。
保留中の削除
適用には非破壊的な変更のみが含まれ、テーブルの削除や列の削除などの変更はpendingDrops変更セットに配置されます。
削除保留中の変更は、マイグレーションに含めるために明示的に選択する必要があります。
クラスタ環境で実行されているアプリケーションの場合、保留中の削除は通常、通常の適用変更より少なくとも1つのマイグレーション遅れる必要があります。この遅延は数分、数日になる場合があり、一部の削除は実行されない場合があります。
マイグレーションXML
DbMigrationが実行されると、モデルに対する差分が決定され、マイグレーションモデルXMLドキュメントとして出力されます。この差分には、適用変更またはpendingDrops変更が含まれる場合があります。
マイグレーションの適用変更セットから、実際に適用されるDDLが生成されます。
論理的な変更
マイグレーションXMLの変更はデータベースに依存せず、単一のマイグレーションXMLドキュメントを使用して、複数のデータベースのマイグレーションDDLを生成できることに注意してください。たとえば、単一のマイグレーションXMLから、Postgres、Oracle、SQL ServerのマイグレーションDDLスクリプトを生成できます。マイグレーションXMLには、JSONタイプ（JSONドキュメントをDBに格納する）などの論理タイプが表示され、Postgresの場合はJSONBに、Oracleの場合はCLOBに変換される場合があります。
@Historyおよび@Draftableを持つエンティティへの変更は、通常、複数の変更に変換されるという意味でも、「論理的」です。たとえば、@Historyエンティティにプロパティを追加すると、ベーステーブルに列が追加され、履歴テーブルに列が追加され、必要に応じてトリガーが変更される可能性があります。
マイグレーションXMLの例
以下は、適用変更で生成されたマイグレーションXMLの例です。 customerテーブルには、2つの新しい列が追加されています。
customerテーブルに@Historyサポートがある場合、履歴テーブルに列を追加し、関連するDBトリガーを更新することもできます。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<migration xmlns="http://ebean-orm.github.io/xml/ns/dbmigration">
<changeSet type="apply">
<addColumn tableName="customer">
<column name="registered" type="date"/>
<column name="comments" type="varchar(1000)"/>
</addColumn>
</changeSet>
</migration>
pendingDropsを使用したマイグレーションの例
以下は、pendingDrops変更で生成されたマイグレーションXMLの例です。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<migration xmlns="http://ebean-orm.github.io/xml/ns/dbmigration">
<changeSet type="pendingDrops">
<dropColumn columnName="shortTitle" tableName="document" withHistory="true"/>
</changeSet>
</migration>
保留中の削除変更は、明示的に選択しない限り、適用DDLスクリプトに組み込まれません。保留中の削除が適用されると、「保留中の削除」リストから削除されます。
DDLの適用
適用ddlスクリプトには、データベースに適用する変更が含まれています。これは、FlywayDBなどを実行して取得するDDLスクリプトです。
保留中の削除の適用
INFO c.a.ebean.dbmigration.DbMigration - Pending un-applied drops in versions [1.2]
DBマイグレーションは、まだ適用されていない保留中の削除を含むマイグレーションをINFOレベルのメッセージでログに記録します。ある時点で、保留中の削除の1つを次のマイグレーションとして適用することが決定されます。
// generate a migration as the drops from migration version "1.2"
System.setProperty("ddl.migration.pendingDropsFor", "1.2");
DbMigration dbMigration = new DbMigration();
dbMigration.setPlatform(DbPlatformName.POSTGRES);
dbMigration.generateMigration();
次に、dropsForを、適用する保留中の削除があったマイグレーションのバージョンに設定して、マイグレーションが生成されます。さらに、マイグレーション適用ddlには、実行されるさまざまな削除ステートメントが含まれています。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<migration xmlns="http://ebean-orm.github.io/xml/ns/dbmigration">
<changeSet type="apply" dropsFor="1.2">
<dropColumn columnName="shortTitle" tableName="document" withHistory="true"/>
</changeSet>
</migration>
バージョン形式
サポートされている「バージョン」番号付け形式は、"."または"_"（ピリオドまたはアンダースコア）を区切り文字として使用できるFlywayDBバージョン番号付けと同じです。
例
したがって、1.1と1_1はどちらもバージョン1.1として解釈されます。
バージョン番号はマイグレーションが実行される順序を制御し、セマンティックバージョン管理に従うため、たとえば1.1.1は1.2の前に実行されることに注意してください。これにより、「パッチ」マイグレーションを追加できます。
ワークフロー
Ebeanのマイグレーションランナーを使用してマイグレーションを実行する場合、マイグレーションを実行するには、前のマイグレーションが実行されている必要があることに注意してください。これは、厳密なバージョン番号の順序を必要とするFlywayDBとは少し異なります（または、それを無効にして任意の順序を許可することもできます）。
「git flow」に似たワークフローを使用している場合、Ebeanのマイグレーションランナーを使用すると、マージリクエストを厳密な順序で処理できます。これが機能するための前提は、2つ以上のマージリクエスト（レビュー中で、共通のDEVブランチにまだマージされていない）がある場合、DBマイグレーションの変更が競合しないことです（競合する場合、Ebeanはマイグレーションの実行を許可しますが、マイグレーション自体エラーになります）。
マイグレーションのバージョンと名前
マイグレーションの場合、開発者はバージョンと名前を提供する必要があり、これらは環境変数、システムプロパティ、ebean.properties、またはプログラムで設定できます。
System.setProperty("ddl.migration.version", "1.1");
System.setProperty("ddl.migration.name", "support end dating");
起動時のマイグレーションの生成
ddl.migration.generateシステムプロパティまたは環境変数をtrueに設定することにより、Ebeanインスタンスの起動時にDBマイグレーションを生成できます。
@Test
public void generate() {
System.setProperty("ddl.migration.generate", "true");
System.setProperty("ddl.migration.version", "1.1");
System.setProperty("ddl.migration.name", "support end dating");
// migration will be generated when Ebean starts
// ... typically by running your application.
DB.getDefault();
}
オフラインでの生成
アプリケーションを起動せずに、プログラムでマイグレーションを生成できます。 src/test/javaに、mainメソッドを含む次のコードを追加します。
このmainメソッドを実行すると、次のマイグレーションが生成され、Ebeanがオフラインモードで起動します。このオフラインモードでは、アプリケーションを起動したり、マイグレーションを生成するためのデータベースを必要としたりする必要はありません。
package main;
import io.ebean.Platform;
import io.ebean.dbmigration.DbMigration;
import java.io.IOException;
/**
* Generate the DB Migration.
*/
public class MainDbMigration {
/**
* Generate the next "DB schema DIFF" migration.
* <p>
* These migration are typically run using FlywayDB, Liquibase
* or Ebean's own built in migration runner.
* </p>
*/
public static void main(String[] args) throws IOException {
// optionally specify the version and name
//System.setProperty("ddl.migration.version", "1.1");
System.setProperty("ddl.migration.name", "support end dating");
// generate a migration using drops from a prior version
//System.setProperty("ddl.migration.pendingDropsFor", "1.2");
DbMigration dbMigration = new DbMigration();
dbMigration.setPlatform(Platform.POSTGRES);
// generate the migration ddl and xml
// ... start in "offline" mode
dbMigration.generateMigration();
}
}
マイグレーションの実行
FlywayDb、Liquibase、またはEbean独自の組み込みマイグレーションランナーを使用して、マイグレーションを実行できます。
Ebeanのマイグレーションランナー
## run migrations when the Ebean starts
ebean.migration.run=true
## optionally specify different DB credentials
## to run the migration (own the tables)
datasource.db.adminusername=myDbTableOwner
datasource.db.adminpassword=secret
ebean.migration.run=trueの場合、Ebeanの起動時にマイグレーションが確認され、実行する必要があるものが実行されます。マイグレーションランナーは、デフォルトでdb_migrationというテーブルを作成します。このテーブルには、実行されたマイグレーションに関するメタデータが保持され、マイグレーションが正常に実行されると、このテーブルに挿入されます。
繰り返し可能なマイグレーション
繰り返し可能なマイグレーションは、R__で始まり、バージョン番号を持たない特別なマイグレーションです。繰り返し可能なマイグレーションは、まだ実行されていない場合、またはコンテンツが変更された場合（MD5チェックサムが変更された場合）に実行されます。
繰り返し可能なマイグレーションには任意のDDLを含めることができますが、ORMでは、これらをデータベースビューの定義に使用します。たとえば、テーブルではなくデータベースビューにエンティティBeanをマッピングするために@Viewを使用します。
extra-ddl.xmlを使用した繰り返し可能なマイグレーションと@Viewでの使用を示す2番目のビデオを参照してください。
繰り返し可能なマイグレーション
@View、extra-ddl.xml、および繰り返し可能なマイグレーションの使用FlywayDBの注意
FlywayDBで使用する場合は、現在、「バージョンマイグレーション」と「繰り返し可能なマイグレーション」の両方をサポートするために、「バージョンマイグレーション」の前にVを付ける必要があります。これを行うには
## must use V prefix on "version migrations" when using FlywayDB
## with both "version" and "repeatable" migrations
ebean.migration.applyPrefix=V