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

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

## 使う理由

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

## 例

```text
lib/resources/
  application.properties
  db/migration/
    V1__books.sql          # 一度、最初に実行される
    V2__add_year.sql       # 一度、V1 の後に実行される
    V2_1__index_title.sql  # バージョン 2.1
    R__views.sql           # 変わるたびに、バージョン付きのものの後に再び実行される
```

```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};
```

```properties
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` (最新の適用済みのものより低いファイルで、一度も適用されていない)、`*` です。

### 既存のデータベース

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

```properties
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>` は、独自のマイグレーション、スクリプト、スキーマのモードを持ちます。

```properties
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](query.md) を参照)。`create table`、`alter table` (列の追加、名前の変更、削除、テーブルの名前の変更)、`drop table`、`create view` を、ファイルが実行される順にたどります。

## Spring (Java) との対応

```properties
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` が最も近いものです。

## 関連項目

- [データソース](data-sources.md)
- [エンティティ](entities.md)
- [すべてのプロパティ](properties.md)
