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 Boot が 4.0 系であることを確認します。4.0.2 が表示されない場合は、利用可能な 4.0 系の安定版を選んでください。
生成された pom.xml の依存関係を確認してください。
Spring Boot 4.0 系で H2 コンソールを使うには spring-boot-h2console が必要です。Initializr で h2 を選ぶと自動で追加されるため、次の依存関係はすでに含まれているはずです。含まれていない場合だけ dependencies 内に追加してください。
Spring Boot の H2 コンソール設定 を参照できます。
DB 接続情報の作成
application.yaml に、データソース定義を追加します。
マイグレーションを体験するためには、 Spring Boot アプリケーションの起動ごとに DB の初期化がされてしまうと困ります。
そのため今回は、 H2 DB を利用し、 ./target/workshopdb.mv.db という名前の DB ファイルを作成し、そこでデータを管理します。
このコンソール設定はローカルの演習用です。
DB ファイルを target 配下に置いているため、./mvnw clean を実行すると演習データも削除されます。
履歴の確認中は clean を実行しないでください。
H2 DB は、デフォルトユーザー名 sa, パスワード無しでログインできるため、そのように設定しています。
起動確認
この時点で正常に起動できるか確認しましょう。
次のコマンドを実行し、 Spring Boot アプリケーションが正常に起動することを確認してください。
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:
これだけで、マイグレーションの準備は完了です。
DDL はテーブルなどの構造を定義する SQL のことです。
ファイル名は V + バージョン + __(アンダースコア 2 個)+ 説明 + .sql とします。
password カラムを実際の認証に使うときは、平文ではなくパスワードハッシュを保存します。
今回は、可読性を重視して「日付.連番」形式を採用しています。 命名規則には、「タイムスタンプ」や「セマンティックバージョニング」などがあります。 プロジェクトの特性や運用条件に応じて選びましょう。 ※ チーム内でルールを統一することが重要です。
Spring Boot アプリケーションの起動とスキーマ確認
それではもう一度 Spring Boot アプリケーションを実行してみましょう。
起動ログに、次のようにマイグレーションの結果が表示されます。
「起動確認」の時点でアプリを一度起動しているため、履歴テーブルがすでに作成されている場合があります。その場合、上の抜粋のうち 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 文でカラム 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 の結果が 2 件のままであることも確認してください。 適用済みファイルを編集すると検証エラーになるため、修正は新しいバージョンのファイルに書きます。
並行開発に向けたマイグレーション運用例(発展)
複数の開発者が SQL を追加するチームでは、バージョン番号の衝突や適用済み SQL の変更を避けるルールが必要です。 次は、未確定の SQL と確定したマイグレーションを分ける運用例です。
「実装中は draft ディレクトリにマイグレーションファイルを作り、 レビュー後、 migration ディレクトリに移動させてマージする」
ただし、この運用をするには次の条件を満たす必要があります。
- 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:
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はスキーマを直さない。
どうやれば自分のプロジェクトに取り入れられるか、皆さんも考えてみてください。