🪶
【Spring Boot】FlywayでDBマイグレーションする

2025/07/05に公開
 この文章の目的SpringBootでFlywayを動かすための手順を残すこと。

新規アプリケーション開発に関わる場合に手早くDBマイグレーション機能を実装できるようにしておくこと。

 環境動作環境
Ubuntu 24.04
Docker 28.2
Docker Compose 2.36.2

アプリ
Amazon Corretto 21.07
Spring Boot 3.5.0

DB
PostgreSQL16.9


 手順アプリとDBのセットアップは完了している前提とする。

 1. build.graldeに依存関係を追加するbuild.gradleに以下の依存ライブラリを追加する。
dependencies {
    ⋮
    implementation 'org.springframework.boot:spring-boot-starter-jdbc'
    implementation 'org.flywaydb:flyway-database-postgresql'
    runtimeOnly 'org.postgresql:postgresql'
    ⋮
}
それぞれの依存ライブラリの役割は下記の通りである。

 org.springframework.boot:spring-boot-starter-jdbc
Spring BootでJDBCを使うための基本的な機能を提供する。これが無いとFlywayがデータベースにアクセスできない。(というより、Flywayが起動すらしなかった。)


org.flywaydb:flyway-database-postgresql
PostgreSQL専用のFlyway拡張機能。PostgreSQL固有の構文やデータ型をサポートするために必要である。

org.postgresql:postgresql
SpringBootがPostgreSQLデータベースに接続するためのJDBCドライバ。これにより実際にデータベースとの接続が可能になる。コンパイル時には不要なのでruntimeOnlyとしている。

spring-boot-starter-jdbcはspring-boot-starter-data-jpaでも問題ない。
公式ドキュメントにはorg.flywaydb:flyway-coreを追加する手順が記載されている。しかし、org.flywaydb:flyway-coreはorg.flywaydb:flyway-database-postgresqlに内蔵されているため、本稿の手順においては不要である。
\--- org.flywaydb:flyway-database-postgresql -> 11.7.2
     \--- org.flywaydb:flyway-core:11.7.2

 2. application.yamlに設定を追加するapplication.yamlに以下の設定を追加する。
spring:
  ⋮
  # DB接続用設定
  datasource:
    url: jdbc:postgresql://localhost:5432/app
    username: <user>
    password: <password>
   # Flyway接続用設定
   flyway:
    default-schema: app
DB接続用設定
spring.datasource.url: JDBCの接続用URL。この設定値はローカルホストの5432番ポートで動作するPostgreSQLのappデータベースに接続することを意味する。

spring.datasource.username: データベースのログインユーザ名。

spring.datasource.password: データベースのパスワード
なお、driver-class-nameは設定する必要がない。datasource.urlの設定に基づいて自動で検出されるためである。
JDBC ドライバーの完全修飾名。デフォルトで URL に基づいて自動検出されます。
Flyway接続用設定
spring.flyway.default-schema: Flywayで利用するデフォルトスキーマを指定する。今回は1つのスキーマしか使わないため設定している。
最初は必要だと思っていたが、調べた結果デフォルト値で問題ない＆設定する必要がなかった設定値を備忘録として記載する。

spring.flyawy.enabled: アプリ起動時にFlywayを実行するかどうかを指定する。デフォルト値はtrue。今回はアプリ起動時にFlywayを実行するため不要。逆に、マイグレーションのタイミングを制御したい場合は明示的にfalseを指定する必要がある。

spring.flyway.locations: マイグレーションSQLのパスを指定する。デフォルト値はclasspass:db/migration。今回はクラスパス下のdb/migrationディレクトリに配置するため不要。

baseline-on-migrate: flyway_schema_historyが無いかつ空ではないスキーマをマイグレーションする際にベースラインを自動的に呼び出すか指定する。trueの場合、指定したバージョン以降からマイグレーションを実行する。

spring.flyway.baseline-version: ベースラインのバージョンを指定する。
`spring.flyway.url, user, password: spring.datasource配下の同名プロパティでDB接続できるので不要

 3. マイグレーションSQLを作るsrc/main/resources配下にdb/migrationディレクトリを作成し、マイグレーションファイルを配置する。
src/main/resources 
├── db
  └── migration
      ├── V1.0.0_202507022100__create_task.sql
      ├── V1.0.0_202507022110__create_label.sql
      └── V1.0.0_202507022120__create_task_label.sql
デフォルトではclasspath:db/migrationにSQLパスを探しに行くので、上記SQLがマイグレーション対象になる。
マイグレーションSQLにはV${version}__{name}.sqlという命名規則がある。versionは一意である必要があるため、アプリのバージョンをを示す1.0.0の後に日時を表す文字列を入れている。(あくまでもversionが一意であればよいので、日時が正確である必要はない。)
上記設定にてアプリの起動時にFlywayを実行することができた。

 終わりに本稿を執筆する上ではGitHub Copilot Chat及び、ChatGPTを利用した。

 参考資料Database initialization
アプリケーションプロパティ設定一覧
この文章の目的

環境

手順

1. build.graldeに依存関係を追加する

2. application.yamlに設定を追加する

DB接続用設定

Flyway接続用設定

3. マイグレーションSQLを作る

終わりに

参考資料

Discussion
