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, and this page is available as Markdown at /Practical-Introduction-to-Spring-Boot/SpringBoot入門/DBマイグレーション入門.md.

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

講義の区切り

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

対象者と到達目標

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

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

Spring Initializr

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

Spring Initializr

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

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

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

Spring Boot の H2 コンソール設定 を参照できます。

DB 接続情報の作成

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

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

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 アプリケーションが正常に起動することを確認してください。

./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:

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 アプリケーションを実行してみましょう。

./mvnw spring-boot:run

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

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:

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 がある行だけを取得します。

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

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

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

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

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

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:

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 設定 を参照してください。

まとめ

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

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

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

参考資料