スキーマとマイグレーション
起動時、リポジトリや 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 テーブルは、両方を示して起動を止めます。
起動時の順序
データソースごとに、一つのステップで:
- 所有者は一つ。
createとcreate-dropは、マイグレーションのファイルや実行すべきspring.sql.initのスクリプトがあると実行を拒否し、マイグレーションはそうしたスクリプトがあると実行を拒否します。Spring Boot と同じです。 - 接続。
spring.sql.migration.connect-retries回、connect-retries-intervalの間隔で再試行します。 - マイグレーション、またはそれがなければ SQL スクリプト。
createとcreate-dropでは、エンティティからのテーブル。validateでは、エンティティのチェック。
データソースは、これが終わるまですべての接続を差し止めます。
マイグレーション
| ファイル | 実行 |
|---|---|
V<version>__<description>.sql |
一度、バージョンの順に。バージョンは . または _ で区切った整数 (1、1.1、1_1、2.10) で、数ごとに比較される: 1.10 は 1.9 の後で、1 は 1.0 と等しい。 |
R__<description>.sql |
チェックサムが変わるたびに、バージョン付きのものの後に再び。 |
一回の実行は:
- ファイルを見つけ、履歴テーブル
schema_history(なければ作成される) を読みます。 - 履歴をファイルと照合して検証します (
validate-on-migrate)。ファイルが変わった、またはなくなった適用済みのマイグレーションは、そのファイルを示して起動を止めます。すべてのファイルより新しい適用済みのバージョンは、デフォルトでは無視されます (*:future)。そのため、アプリケーションの後のバージョンのデータベースでも起動できます。 - 保留中の各マイグレーションを、プレースホルダーを置き換えた後、それぞれ独自のトランザクションで (
groupならすべてを一つで) 適用します。失敗したマイグレーションはロールバックされ、記録されず、ファイル、文の番号と行、データベースのメッセージを示して起動を止めます。 - 実行全体を通してマイグレーションのロックを保持するため、同時に起動した複数のインスタンスは一度だけマイグレーションします。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 |
ファイルのエンコーディング。 |
- ないデフォルトのスクリプトはスキップされます。指定したロケーションは、
optional:で始まらない限り存在しなければなりません。ロケーションの中の@@platform@@はプラットフォームに置き換えられます。 - 失敗した文は、
continue-on-errorでない限り、ファイルと行を示して起動を止めます。
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 が最も近いものです。