スキーマとマイグレーション

起動時、リポジトリや JdbcTemplate がデータベースを使える前に、スターターはそのスキーマを準備します。マイグレーション (lib/resources/db/migration/V1__books.sql。Flyway のファイル命名) を実行するか、マイグレーションがなければ SQL スクリプト (schema.sql、data.sql) を実行します。その後、エンティティをテーブルと照合する (spring.data.jdbc.schema=validate、デフォルト) か、エンティティからテーブルを作成します (create)。

使う理由

スキーマはアプリケーションとともに変わります。新しいテーブル、新しい列、名前の変わった列などです。マイグレーションは各変更を番号付きのファイルとして記録し、すべてのデータベースでそれぞれを一度だけ実行し、何が実行されたかを覚えています。エンティティとの照合は、スキーマに合わないマッピングを、本番の最初のクエリではなく、起動時に明確なメッセージとともに捕まえます。

例

lib/resources/
  application.properties
  db/migration/
    V1__books.sql          # 一度、最初に実行される
    V2__add_year.sql       # 一度、V1 の後に実行される
    V2_1__index_title.sql  # バージョン 2.1
    R__views.sql           # 変わるたびに、バージョン付きのものの後に再び実行される
-- V1__books.sql
create table books (
  id integer primary key autoincrement,
  title text not null,
  version integer not null
);

-- V2__add_year.sql
alter table books add column year integer;

-- R__views.sql
drop view if exists recent_books;
create view recent_books as select * from books where year > ${recent-year};
spring.datasource.url=sqlite:file:library.db
spring.sql.migration.placeholders.recent-year=2000
# デフォルト: 各エンティティのテーブルと列をデータベースと照合する。
spring.data.jdbc.schema=validate

起動時、ログ (ロガー spring.sql.migration) は適用したバージョンを示し、Book が宣言する year 列のない books テーブルは、両方を示して起動を止めます。

起動時の順序

データソースごとに、一つのステップで:

  1. 所有者は一つ。 create と create-drop は、マイグレーションのファイルや実行すべき spring.sql.init のスクリプトがあると実行を拒否し、マイグレーションはそうしたスクリプトがあると実行を拒否します。Spring Boot と同じです。
  2. 接続。 spring.sql.migration.connect-retries 回、connect-retries-interval の間隔で再試行します。
  3. マイグレーション、またはそれがなければ SQL スクリプト。
  4. create と create-drop では、エンティティからのテーブル。
  5. validate では、エンティティのチェック。

データソースは、これが終わるまですべての接続を差し止めます。

マイグレーション

ファイル 実行
V<version>__<description>.sql 一度、バージョンの順に。バージョンは . または _ で区切った整数 (1、1.1、1_1、2.10) で、数ごとに比較される: 1.10 は 1.9 の後で、1 は 1.0 と等しい。
R__<description>.sql チェックサムが変わるたびに、バージョン付きのものの後に再び。

一回の実行は:

  1. ファイルを見つけ、履歴テーブル schema_history (なければ作成される) を読みます。
  2. 履歴をファイルと照合して検証します (validate-on-migrate)。ファイルが変わった、またはなくなった適用済みのマイグレーションは、そのファイルを示して起動を止めます。すべてのファイルより新しい適用済みのバージョンは、デフォルトでは無視されます (*:future)。そのため、アプリケーションの後のバージョンのデータベースでも起動できます。
  3. 保留中の各マイグレーションを、プレースホルダーを置き換えた後、それぞれ独自のトランザクションで (group ならすべてを一つで) 適用します。失敗したマイグレーションはロールバックされ、記録されず、ファイル、文の番号と行、データベースのメッセージを示して起動を止めます。
  4. 実行全体を通してマイグレーションのロックを保持するため、同時に起動した複数のインスタンスは一度だけマイグレーションします。SQLite では書き込みロックで、lock-timeout まで再試行します。PostgreSQL ではアドバイザリーロックです。他のインスタンスは待ち、その後何もすることがないことを知ります。

clean コマンドはありません。ランナーは決して何も削除しません。ログの行はバージョン、説明、件数を示し、値は決して示しません。

マイグレーションの設定

キー デフォルト 意味
spring.sql.migration.enabled true マイグレーションを実行するかどうか。ファイルがなければ、いずれにせよ何も実行されない。
spring.sql.migration.locations resources:db/migration ファイルの場所。{vendor} は方言の名前に置き換えられる: resources:db/migration/{vendor} は db/migration/sqlite または db/migration/postgresql を読む。
spring.sql.migration.table schema_history 履歴テーブル。
spring.sql.migration.validate-on-migrate true 変わった、またはない適用済みのファイルや、適用済みのものより古い未適用のファイルは、起動を止める。
spring.sql.migration.target latest マイグレーションの目標バージョン。繰り返し可能なマイグレーションは latest でだけ実行される。
spring.sql.migration.out-of-order false 最新の適用済みのものより低いバージョンのファイルも実行するかどうか。
spring.sql.migration.ignore-migration-patterns *:future 無視する履歴の問題。type:status の形で。
spring.sql.migration.baseline-on-migrate false テーブルがあって履歴のないデータベースを、起動を止める代わりに baseline-version にあるものとみなす。
spring.sql.migration.baseline-version 1 ベースラインのバージョン。
spring.sql.migration.baseline-description << Baseline >> ベースラインの説明。
spring.sql.migration.placeholders.<name> なし ファイル内の ${name} の値。
spring.sql.migration.placeholder-replacement true プレースホルダーを置き換えるかどうか。
spring.sql.migration.placeholder-prefix ${ プレースホルダーの始まり。空であってはならない。
spring.sql.migration.placeholder-suffix } プレースホルダーの終わり。空であってはならない。
spring.sql.migration.group false 保留中のすべてのマイグレーションを一つのトランザクションで。
spring.sql.migration.connect-retries 0 起動時に失敗した接続を再試行する回数。
spring.sql.migration.connect-retries-interval 10s 2 回の試行の間の待機。
spring.sql.migration.lock-timeout 1m 別のプロセスが保持するマイグレーションのロックを待つ時間。

ignore-migration-patterns のエントリーは type:status で、type は versioned、repeatable、*、status は missing (適用済みで、ファイルになく、最新のファイルより低い)、future (適用済みで、すべてのファイルより新しい)、ignored (最新の適用済みのものより低いファイルで、一度も適用されていない)、* です。

既存のデータベース

すでにテーブルのあるデータベースで履歴を始めるには:

spring.sql.migration.baseline-on-migrate=true
spring.sql.migration.baseline-version=3

履歴はバージョン 3 にベースラインを記録します。V3__... までのファイルは適用済みとみなされ、V4__... 以降が実行されます。

Spring Boot の名前

ランナーはスターター独自のもので、Flyway のファイル命名と履歴を持ちます。Spring Boot の spring.flyway.* の名前は使われず、その下のキーは、代わりに使うべき spring.sql.migration.* のキーを示して起動を止めます。

SQL スクリプト

マイグレーションがなければ、Spring Boot と同じく、lib/resources/ の schema.sql と data.sql が起動時に実行されます。単純な場合やテスト向けです。

キー デフォルト 意味
spring.sql.init.mode embedded スクリプトを実行するタイミング: embedded (メモリ上のデータベース sqlite::memory: でだけ)、always、never。
spring.sql.init.schema-locations resources:schema.sql、resources:schema-<platform>.sql スキーマのスクリプト。
spring.sql.init.data-locations resources:data.sql、resources:data-<platform>.sql データのスクリプト。スキーマのスクリプトの後に実行される。
spring.sql.init.platform all プラットフォームのスクリプトの名前に入るプラットフォーム。
spring.sql.init.continue-on-error false 失敗した文を、起動を止める代わりにログに出してスキップするかどうか。
spring.sql.init.separator ; 文の区切り。
spring.sql.init.encoding utf-8 ファイルのエンコーディング。

spring.data.jdbc.schema

値 スターターが行うこと
none 何もしない。
validate (デフォルト) エンティティのテーブルと列が存在し、合っていることをチェックする: 型、nullable かどうか、その ON DELETE を伴う外部キー、一意キー。外部キーのない参照は警告。
create エンティティからないテーブルを、外部キー、参照のインデックス、一意制約とともに作成する。
create-drop テーブルを作成し、コンテキストが閉じるときに削除する。

create と create-drop は、マイグレーションやスクリプトとともに使うものではありません。決して削除も名前の変更もせず、スキーマをずれたままにする update モード (Hibernate のもの) はありません。マイグレーションを書いてください。

チェックまたは作成されるエンティティは、そのデータソース上のリポジトリのものと、その子です。

名前付きのデータベース

各 spring.datasources.<name> は、独自のマイグレーション、スクリプト、スキーマのモードを持ちます。

spring.datasources.stats.url=sqlite:file:stats.db
spring.datasources.stats.sql.migration.locations=resources:db/stats
spring.datasources.stats.data.jdbc.schema=validate

ビルドもスキーマを読む

ビルドは、@Query のテキストのテーブル名と列名をチェックするために、lib/resources/ のマイグレーションと schema.sql を読みます (@Query を参照)。create table、alter table (列の追加、名前の変更、削除、テーブルの名前の変更)、drop table、create view を、ファイルが実行される順にたどります。

Spring (Java) との対応

spring.flyway.locations=classpath:db/migration
spring.jpa.hibernate.ddl-auto=validate

ここではマイグレーションは spring.sql.migration.* (Flyway の命名、スターターのランナー) で、スキーマのモードは spring.data.jdbc.schema です。Spring Data JDBC 自体にはスキーマのチェックがありません。Hibernate の ddl-auto が最も近いものです。

関連項目