Gradleを用いたFlywayのセットアップ方法：GradleプラグインとSpring Boot

FlywayをGradleプロジェクトへ組み込む方法は、大きく2つあります。

1. GradleのタスクとしてFlywayを実行する
2. Spring Bootの起動時にFlywayを実行する

どちらを選ぶかで、マイグレーションを実行するタイミングと、SQLファイルの配置場所が変わります。この記事では、まずGradleプラグインを使う方法を確認し、その後でSpring Bootに組み込む方法を説明します。

CLIで設定ファイルを用意して実行する方法は、Flywayの導入と初期設定を参照してください。

1. Gradleプラグインとして導入する

Gradleプラグインを使うと、flywayInfo や flywayMigrate のようなGradleタスクからFlywayを実行できます。アプリケーションを起動せず、CI/CDやデプロイ処理から明示的にマイグレーションを実行したい場合に向いています。

前提

Flywayの現行Gradleプラグインは、公式ドキュメント上ではGradle 7.6系・8系とJava 17を前提にしています。実際には、Flywayのバージョン、Gradle、Javaの組み合わせをプロジェクトの依存関係と合わせてください。

build.gradle を設定する

以下はGroovy DSLの build.gradle を使う例です。既存プロジェクトが build.gradle.kts の場合は、文字列やリストの書き方が変わるため、そのまま貼り付けないでください。

plugins {
    id 'java'
    id 'org.flywaydb.flyway' version '13.7.0'
}

repositories {
    mavenCentral()
}

dependencies {
    // Flywayが接続するデータベースのドライバー
    runtimeOnly 'com.h2database:h2:2.2.224'
}

flyway {
    url = 'jdbc:h2:file:./build/data/appdb'
    user = 'sa'
    password = ''
    locations = ['classpath:db/migration']
}

バージョン番号は固定して管理し、プロジェクトで採用するFlywayのリリースに合わせて更新します。サンプルの 13.7.0 は公式ドキュメントに掲載されている例です。

SQLファイルの配置場所

Gradleプラグインで classpath:db/migration を指定した場合、SQLファイルは次の場所に配置します。

src/
└── main/
    └── resources/
        └── db/
            └── migration/
                ├── V1__create_users.sql
                └── V2__add_points_to_users.sql

V1__create_users.sql の例です。

CREATE TABLE users (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

V2__add_points_to_users.sql では、次のようにテーブルを変更します。

ALTER TABLE users
    ADD COLUMN points INTEGER NOT NULL DEFAULT 0;

Gradleタスクを実行する

まず、現在の状態を確認します。

./gradlew flywayInfo

ファイルの内容と、適用済みのマイグレーションに不一致がないかを確認します。

./gradlew flywayValidate

問題がなければ、未適用のマイグレーションを実行します。

./gradlew flywayMigrate

Gradleプラグインでは、ほかにも次のタスクを利用できます。

タスク	用途
flywayInfo	マイグレーションの状態を表示する
flywayValidate	適用済みファイルとの差分を検証する
flywayMigrate	未適用のマイグレーションを実行する
flywayBaseline	既存データベースを基準バージョンから管理する
flywayRepair	スキーマ履歴のメタデータを修復する
flywayClean	管理対象のオブジェクトを削除する。ローカル専用

flywayClean はデータを削除するため、共有環境や本番環境では実行しないでください。

接続情報をソースコードへ書かない

ユーザー名やパスワードを build.gradle に直接書くと、リポジトリへ認証情報を登録してしまう危険があります。コマンドラインのシステムプロパティやCI/CDのシークレットを利用します。

./gradlew \
  -Dflyway.url="jdbc:postgresql://localhost:5432/app" \
  -Dflyway.user="$DB_USER" \
  -Dflyway.password="$DB_PASSWORD" \
  flywayMigrate

また、Flywayの設定ファイルを別に用意して flyway.configFiles で指定する方法もあります。認証情報を含むファイルは、リポジトリへコミットしないようにします。

PostgreSQLなどのデータベースを使う場合

利用するデータベースに応じて、JDBCドライバーとFlywayのデータベースモジュールが必要になる場合があります。例えばPostgreSQLでは、プロジェクトで利用しているFlywayのバージョンに合わせて次のような依存関係を追加します。

dependencies {
    runtimeOnly 'org.postgresql:postgresql:<POSTGRESQL_DRIVER_VERSION>'
    implementation 'org.flywaydb:flyway-database-postgresql:<FLYWAY_VERSION>'
}

具体的なモジュール名や対応バージョンは、採用しているFlywayの公式ドキュメントを確認してください。実行時に No Flyway database plugin found to handle ... と表示された場合は、データベースモジュールがGradleの実行クラスパスに入っているかを確認します。

2. Spring Bootに組み込む

Spring Bootでは、Flywayを依存関係へ追加するとアプリケーション起動時にマイグレーションを実行できます。

アプリケーションの起動とデータベースのスキーマ更新を同じライフサイクルで扱いたい場合に向いています。

依存関係を追加する

Spring Bootのバージョンに対応した依存関係管理を利用する前提で、Flywayのスターターとデータベースドライバーを追加します。

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-flyway'
    runtimeOnly 'com.h2database:h2'
}

PostgreSQLやMySQLなどを利用する場合は、データベースのJDBCドライバーと、必要なFlywayデータベースモジュールも追加します。

SQLファイルの配置場所

Spring Bootのデフォルト配置先は classpath:db/migration です。

src/
└── main/
    └── resources/
        └── db/
            └── migration/
                ├── V1__create_users.sql
                └── V2__add_points_to_users.sql

application.yml で接続先を設定します。

spring:
  datasource:
    url: jdbc:h2:file:./build/data/appdb
    username: sa
    password:
  flyway:
    locations: classpath:db/migration

配置場所を変更したいときは、spring.flyway.locations を設定します。

spring:
  flyway:
    locations:
      - classpath:db/migration
      - classpath:db/migration/${DB_VENDOR}

アプリケーション起動時にSpring Bootが Flyway.migrate() を呼び出し、未適用のマイグレーションを実行します。

JPAのDDL自動生成と併用しない

FlywayとHibernateの ddl-auto=create や update、schema.sql、data.sql を同時に使うと、どの仕組みがスキーマを変更したのか分からなくなります。

本番相当の環境では、スキーマ変更をFlywayに集約し、JPAを使う場合も次のように検証だけにする構成が分かりやすいです。

spring:
  jpa:
    hibernate:
      ddl-auto: validate

テスト用データだけを用意したい場合は、src/test/resources/db/migration にテスト専用のマイグレーションを置く方法があります。

GradleプラグインとSpring Bootの使い分け

観点	Gradleプラグイン	Spring Boot
実行タイミング	flywayMigrate を実行したとき	アプリケーション起動時
主な用途	CI/CD、デプロイ処理、明示的なDB更新	アプリとDB更新を同じ起動フローで管理
SQLの配置	classpath:db/migration などを設定	classpath:db/migration がデフォルト
注意点	実行者がタスクを呼び出す必要がある	起動時にDBへ接続できないと起動に影響する

同じデータベースに対して、GradleタスクとSpring Bootの起動処理を無計画に両方実行するのは避けます。実行されるマイグレーションは履歴で重複適用されませんが、どの処理がデプロイを担当するのかを決めておくことが重要です。

まとめ

GradleでFlywayを使うときは、次のように考えると整理しやすくなります。

1. Gradleのタスクから明示的に実行したいなら、Flyway Gradleプラグインを使う
2. アプリケーション起動時に自動実行したいなら、Spring BootのFlywayスターターを使う
3. 適用済みSQLは編集せず、新しいバージョンのマイグレーションを追加する
4. 本番の認証情報を build.gradle やリポジトリへ保存しない
5. info、validate を実行してから migrate する

参考：

• Gradle Task（Flyway公式）
• Quickstart - Gradle（Flyway公式）
• Database Initialization（Spring Boot公式）