> For AI agents: the complete documentation index is available at /Practical-Introduction-to-Spring-Boot/llms.txt, the full documentation bundle is available at /Practical-Introduction-to-Spring-Boot/llms-full.txt.

# Spring Boot と Flyway で実現する DB マイグレーション - DB を壊さず開発から運用まで行う方法

## 講義の区切り

基本編の目安は 60 分です。終了条件は「2本のマイグレーションと履歴を確認」です。
発展内容・次回の目安: 並行開発・outOfOrder。基本の確認後に取り組んでください。
準備と前後の章は [学習ガイド](/Practical-Introduction-to-Spring-Boot/introduction.md) で確認できます。

## 対象者と到達目標

Spring Boot アプリを起動でき、SQL の CREATE TABLE / ALTER TABLE を読める方が対象です。
DB マイグレーションは、テーブル構造の変更を SQL ファイルとして管理し、順番に適用する仕組みです。
Flyway は適用したファイルを履歴テーブルに記録し、未適用の変更だけを実行します。

このハンズオンでは、テーブル作成、カラム追加、再起動時の適用履歴を確認します。
並行開発の運用例は発展内容です。まずローカル DB でこの 3 点を確認してください。

## Spring Initializr

次のリンクから Spring Initializr を開き、 Spring Boot プロジェクトを作成してください。

[Spring Initializr](https://start.spring.io/#!type=maven-project\&language=java\&platformVersion=4.0.2\&packaging=jar\&configurationFileFormat=yaml\&jvmVersion=21\&groupId=dev.mikoto2000.springboot\&artifactId=flyway\&name=flyway\&description=Demo%20project%20for%20Spring%20Boot%20and%20Flyway\&packageName=dev.mikoto2000.springboot.flyway\&dependencies=devtools,lombok,web,data-jdbc,h2,flyway)

生成前に Spring Boot が 4.0 系であることを確認します。4.0.2 が表示されない場合は、利用可能な 4.0 系の安定版を選んでください。

生成された `pom.xml` の依存関係を確認してください。
Spring Boot 4.0 系で H2 コンソールを使うには `spring-boot-h2console` が必要です。Initializr で `h2` を選ぶと自動で追加されるため、次の依存関係はすでに含まれているはずです。含まれていない場合だけ `dependencies` 内に追加してください。

```xml
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-h2console</artifactId>
</dependency>
```

[Spring Boot の H2 コンソール設定](https://docs.spring.io/spring-boot/4.0/reference/data/sql.html#data.sql.h2-web-console) を参照できます。

## DB 接続情報の作成

`application.yaml` に、データソース定義を追加します。

マイグレーションを体験するためには、 Spring Boot アプリケーションの起動ごとに DB の初期化がされてしまうと困ります。
そのため今回は、 H2 DB を利用し、 `./target/workshopdb.mv.db` という名前の DB ファイルを作成し、そこでデータを管理します。

```yaml
spring:
  application:
    name: flyway

  # 追加ここから
  datasource:
    url: ${DATASOURCE_URL:jdbc:h2:file:./target/workshopdb}
    username: ${DATASOURCE_USERNAME:sa}
    password: ${DATASOURCE_PASSWORD:}
    driver-class-name: org.h2.Driver
  h2:
    console:
      enabled: true
  # 追加ここまで
```

このコンソール設定はローカルの演習用です。
DB ファイルを `target` 配下に置いているため、`./mvnw clean` を実行すると演習データも削除されます。
履歴の確認中は `clean` を実行しないでください。

H2 DB は、デフォルトユーザー名 `sa`, パスワード無しでログインできるため、そのように設定しています。

## 起動確認

この時点で正常に起動できるか確認しましょう。

次のコマンドを実行し、 Spring Boot アプリケーションが正常に起動することを確認してください。

```bash
./mvnw spring-boot:run
```

## H2 コンソールの確認

Spring Boot アプリケーションを起動した状態で `http://localhost:8080/h2-console` に接続すると、 H2 コンソールを確認できます。

H2 コンソールでは、 H2 が管理している DB の状態が確認できます。
今回は、 DB マイグレーションの結果をこの H2 コンソールを用いて確認していきます。

H2 コンソールのログイン画面が開くので、 `application.yaml` に記載したものと同じ接続情報を入力し、 `Connect` ボタンを押してください。

接続情報は JDBC URL: `jdbc:h2:file:./target/workshopdb`、User Name: `sa`、Password: 空欄です。
ログインできたら、Ctrl+C でアプリを停止して次へ進みます。

## 初期スキーマの作成

`src/main/resources/db/migration` に DDL を格納すると、 Spring Boot アプリケーション起動時に Flyway が走り、マイグレーションしてくれます。
(`src/main/resources/db/migration` は Flyway のデフォルト探索パス)

今回は `ACCOUNT` テーブルを作ってみましょう。

`src/main/resources/db/migration/V20260203.01__add_account_table.sql`:

```sql
CREATE TABLE ACCOUNT (
  id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  name VARCHAR(50),
  password VARCHAR(255)
);
```

これだけで、マイグレーションの準備は完了です。
DDL はテーブルなどの構造を定義する SQL のことです。
ファイル名は `V` + バージョン + `__`（アンダースコア 2 個）+ 説明 + `.sql` とします。
`password` カラムを実際の認証に使うときは、平文ではなくパスワードハッシュを保存します。

:::note
今回は、可読性を重視して「日付.連番」形式を採用しています。
命名規則には、「タイムスタンプ」や「セマンティックバージョニング」などがあります。
プロジェクトの特性や運用条件に応じて選びましょう。
※ チーム内でルールを統一することが重要です。
:::

## Spring Boot アプリケーションの起動とスキーマ確認

それではもう一度 Spring Boot アプリケーションを実行してみましょう。

```bash
./mvnw spring-boot:run
```

起動ログに、次のようにマイグレーションの結果が表示されます。

```text
2026-02-04T10:45:41.784Z  INFO 170450 --- [flyway] [  restartedMain] o.f.c.i.s.JdbcTableSchemaHistory         : Schema history table "PUBLIC"."flyway_schema_history" does not exist yet
2026-02-04T10:45:41.786Z  INFO 170450 --- [flyway] [  restartedMain] o.f.core.internal.command.DbValidate     : Successfully validated 1 migration (execution time 00:00.006s)
2026-02-04T10:45:41.789Z  INFO 170450 --- [flyway] [  restartedMain] o.f.c.i.s.JdbcTableSchemaHistory         : Creating Schema History table "PUBLIC"."flyway_schema_history" ...
2026-02-04T10:45:41.808Z  INFO 170450 --- [flyway] [  restartedMain] o.f.core.internal.command.DbMigrate      : Current version of schema "PUBLIC": << Empty Schema >>
2026-02-04T10:45:41.811Z  INFO 170450 --- [flyway] [  restartedMain] o.f.core.internal.command.DbMigrate      : Migrating schema "PUBLIC" to version "20260203.01 - add account table"
2026-02-04T10:45:41.821Z  INFO 170450 --- [flyway] [  restartedMain] o.f.core.internal.command.DbMigrate      : Successfully applied 1 migration to schema "PUBLIC", now at version v20260203.01 (execution time 00:00.003s)
2026-02-04T10:45:41.914Z  INFO 170450 --- [flyway] [  restartedMain] o.s.b.h.a.H2ConsoleAutoConfiguration     : H2 console available at '/h2-console'. Database available at 'jdbc:h2:file:./target/workshopdb'
```

:::note
「起動確認」の時点でアプリを一度起動しているため、履歴テーブルがすでに作成されている場合があります。その場合、上の抜粋のうち `Schema history table ... does not exist yet` と `Creating Schema History table ...` の 2 行は表示されません。`Successfully applied 1 migration` まで進んでいれば成功です。
:::

ログ上では成功しているので、 `http://localhost:8080/h2-console` にアクセスし、テーブル定義が存在するか確認してみましょう。

テーブル一覧にテーブル `ACCOUNT` が存在していることを確認してください。

また、テーブル `flyway_schema_history` が存在していることに気付いた方もいるでしょう。
このテーブルは、 Flyway が行ったマイグレーションの履歴を管理するためのテーブルです。
消したり手動で変更したりしないようにしましょう。

このように、適用したマイグレーションファイルを Flyway が管理するため、
マイグレーションが完了したら、作成したマイグレーションファイルを編集しないようにしましょう。

間違いや仕様変更でスキーマが変更されたら、新しいマイグレーションファイルを追加して対応していきます。

## スキーマの更新ファイル作成

それではさっそく、「仕様変更でテーブル `ACCOUNT` にカラム `ROLE` が必要となった」という想定で、
新しいマイグレーションファイルを作成してみましょう。

`src/main/resources/db/migration/V20260203.02__add_role_column_to_account_table.sql`:

```sql
ALTER TABLE ACCOUNT ADD COLUMN role VARCHAR(50);
```

ALTER 文でカラム `ROLE` を追加するマイグレーションファイルを新規作成しました。

今回は既存行にも追加できるように、null を許可したカラムを追加します。
expand / contract は、先に互換性を保つ変更を追加し、データとアプリを移行した後で古い構造を整理する考え方です。
例えば、カラム追加 → 既存行の値を埋める → 新しいアプリで利用する → 必要なら NOT NULL を付ける、という順に進めます。
この教材で実行するのはカラム追加までです。後続の制約追加は運用設計に応じて別のマイグレーションにします。

## Spring Boot アプリケーションの起動と更新したスキーマの確認

起動中のアプリを Ctrl+C で停止し、`./mvnw spring-boot:run` で起動し直します。
H2 コンソールへ再接続し、カラムが追加されているか確認してください。

Spring Boot 起動時に Flyway が自動実行されるため、新しいマイグレーションが適用されます。

カラムが追加されていることが確認できれば OK です。
次の SQL で、バージョン付きの適用履歴が 2 件あり、いずれも `success` が `true` であることを確認します。
Flyway のバージョンによっては履歴テーブルを作成した記録も残るため、`version` がある行だけを取得します。

```sql
SELECT "version", "description", "success"
FROM "flyway_schema_history"
WHERE "version" IS NOT NULL
ORDER BY "installed_rank";
```

もう一度停止・起動し、同じ SQL の結果が 2 件のままであることも確認してください。
適用済みファイルを編集すると検証エラーになるため、修正は新しいバージョンのファイルに書きます。

## 並行開発に向けたマイグレーション運用例（発展）

複数の開発者が SQL を追加するチームでは、バージョン番号の衝突や適用済み SQL の変更を避けるルールが必要です。
次は、未確定の SQL と確定したマイグレーションを分ける運用例です。

「実装中は draft ディレクトリにマイグレーションファイルを作り、
レビュー後、 migration ディレクトリに移動させてマージする」

```text
feature branch を作成
↓
draft ディレクトリ内で SQL を書く
↓
PR（draft状態）
↓
レビューOK
↓
migration へ移動（Vxxxに変換）
↓
PR更新
↓
最終レビュー
↓
Pull Request をマージ
```

ただし、この運用をするには次の条件を満たす必要があります。

- Git のブランチと Pull Request を使ったレビューができる
- draft の SQL を試すための、一時的な開発用 DB がある
- 確定時にバージョン番号の重複と適用順を確認する

draft ディレクトリは Flyway が自動実行する場所ではありません。SQL を試す方法もチームで決めます。
DB をリセットするのは使い捨ての開発環境に限り、共有環境では適用済みの履歴を維持します。

このあたりの運用は、自分のプロジェクトの特性に合わせ、自分で考えフィットさせていくようにしましょう。

### 複数人でバージョンを採番するとき

本編で `V20260203.01` と `V20260203.02` を適用した、使い捨てのローカル DB をそのまま使います。適用済み SQL は変更しません。アプリを停止し、次のファイルを追加してください。

`src/main/resources/db/migration/V20260203.01.1__add_account_note.sql`:

```sql
ALTER TABLE ACCOUNT ADD COLUMN note VARCHAR(100);
```

Flyway は版番号を数値の区切りとして比較するので、`20260203.01 < 20260203.01.1 < 20260203.02` となります。

既定の `outOfOrder=false` のまま再起動します。起動ログにバージョン `20260203.01.1` の未適用を示す検証エラーが出ることを確認してください。

復旧するには、`src/main/resources/db/migration` に追加した `V20260203.01.1__add_account_note.sql` を削除します。
Maven が `target/classes/db/migration` にコピーした同名ファイルも、残っていれば削除してください。
DB ファイルを保持するため、`./mvnw clean` は実行せずにアプリを起動し直します。
履歴を再度照会し、適用済みの2件が残っていることを確認します。

未配布の変更は、マージ時に共有環境の最新バージョンより大きい番号へ採番します。
適用済みのファイルは変更せず、新しい番号の修正マイグレーションを追加します。
`outOfOrder=true` を使う場合は、適用順が異なる環境でも同じスキーマになるかを検証します。
履歴を合わせるためだけに `repair` を実行しても、スキーマは修正されません。
[Flyway の outOfOrder 設定](https://documentation.red-gate.com/fd/flyway-out-of-order-setting-277579015.html) を参照してください。

## まとめ

今回は、 Spring Boot と Flyway を組み合わせて使った場合の基本的な挙動について学びました。

- `src/main/resources/db/migration` に `V<バージョン>__<説明>.sql` を置くと、起動時に Flyway が未適用分だけを実行する。
- 適用結果は `flyway_schema_history` に記録され、再起動しても適用済みファイルは再実行されない。
- 適用済みファイルは編集せず、変更は新しいバージョンのファイルとして追加する。
- 履歴を合わせるためだけの `repair` はスキーマを直さない。

どうやれば自分のプロジェクトに取り入れられるか、皆さんも考えてみてください。

## 参考資料

- expand / contract
  - [Expand and Contract パターンによる破壊的変更の段階的適用](https://zenn.dev/babyjob/articles/4bfe61d366c6c0)
  - [スキーマの変更をデプロイする方法 - そこに仁義はあるのか(仮)](https://syobochim.hatenablog.com/entry/2020/05/20/084736)
  - [データベースを止めずにテーブル設計を変更したい](https://zenn.dev/praha/articles/abceef00258275)
