Flyway の導入と初期設定：CLIでマイグレーションを実行する

データベースのテーブルやインデックスを直接変更していると、「どの環境に、どの変更を、どの順番で適用したのか」が分からなくなりがちです。

Flywayでは、データベースへの変更をSQLファイルとしてバージョン管理します。Flywayが適用済みのマイグレーションをスキーマ履歴テーブルに記録するため、開発・テスト・本番で同じ変更を同じ順序で適用できます。

この記事では、Flywayのコマンドライン版（CLI）を使って、次の流れを確認します。

Flywayをインストールする
プロジェクトと接続先を設定する
最初のマイグレーションを作成する
info、validate、migrate で状態確認と適用を行う

GradleプロジェクトやSpring Bootに組み込む方法は、Gradleを用いたFlywayのセットアップで説明します。

Flywayの基本

Flywayで管理するデータベースの変更を、マイグレーションと呼びます。

例えば、次のようなSQLファイルをリポジトリに追加します。

V1__create_users.sql
V2__add_points_to_users.sql

Flywayはファイル名からバージョンを読み取り、まだ適用されていないファイルだけを順番に実行します。適用状況はデータベース内の flyway_schema_history テーブルで管理されます。

すでに適用したバージョン済みマイグレーションは、原則として編集しません。既存の変更を修正したい場合は、次のバージョンのマイグレーションを追加します。

Flyway CLIをインストールする

Flyway CLIはWindows、macOS、Linuxで利用できます。公式の配布ファイルをダウンロードして展開し、flyway（Windowsでは flyway.cmd）にPATHを通します。

インストール後、次のコマンドで実行できることを確認します。

flyway --version

Flywayの配布ディレクトリには、設定ファイルを置く conf/、JDBCドライバーを置く drivers/、標準のSQL配置先である sql/ などが含まれます。

使用するデータベースによっては、対応するJDBCドライバーを drivers/ に追加する必要があります。接続できないときは、最初に対象データベースのドライバーがFlywayに含まれているかを確認しましょう。

プロジェクトの構成

この記事では、プロジェクトごとに接続先を管理できるTOML形式を使用します。

my-project/
├── flyway.toml
├── flyway.user.toml       # 個人環境だけの設定。必要ならGit管理対象外にする
└── sql/
    ├── V1__create_users.sql
    └── V2__add_points_to_users.sql

flyway.toml にはチームで共有できる設定を、flyway.user.toml には個人の接続情報などを分けて保存できます。本番のパスワードやトークンをリポジトリに平文で保存してはいけません。

`flyway.toml` を設定する

まずはローカルで確認しやすいSQLiteを例にします。

[flyway]
locations = ["filesystem:sql"]

[environments.local]
url = "jdbc:sqlite:./data/app.db"
username = ""
password = ""

environments は接続先のまとまりです。local という名前の環境を、コマンドの -environment=local で選択します。

PostgreSQLなど別のデータベースを使う場合は、接続先をプロジェクトに合わせて変更します。パスワードは環境変数から解決する形にしておくと、設定ファイルへ直接書かずに済みます。

[flyway]
locations = ["filesystem:sql"]

[environments.development]
url = "jdbc:postgresql://localhost:5432/app"
username = "${env.DB_USER}"
password = "${env.DB_PASSWORD}"

実行前に、接続情報を環境変数へ設定します。

export DB_USER=app_user
export DB_PASSWORD='your-password'

TOML形式は、開発・検証・本番など複数の環境を1つのファイルで管理できます。環境ごとにURLや認証情報を分けられるため、コマンドの中に接続先を毎回書く必要がありません。

なお、以前から使われている flyway.conf 形式も利用できます。ただし、同じ実行環境でTOMLとCONFを混在させると、どちらが読み込まれるか分かりにくくなります。新しく作るプロジェクトではTOMLに統一するのがおすすめです。

マイグレーションを作成する

V1：テーブルを作成する

sql/V1__create_users.sql を作成します。

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(100) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

ファイル名は次の形です。

V<バージョン>__<説明>.sql

V1 がバージョン、__ が区切り文字、create_users が説明です。命名規則の詳細は、Flywayのバージョンや実行順の管理方法で説明します。

V2：テーブルを変更する

次に、sql/V2__add_points_to_users.sql を作成します。

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

一度 V1 を適用したあとに V2 を追加して migrate を実行すると、Flywayは V2 だけを適用します。V1 をもう一度実行することはありません。

状態を確認する

info は、適用済み・未適用・失敗など、マイグレーションの状態を確認するコマンドです。

flyway -environment=local info

初回は、V1 と V2 が未適用の状態で表示されます。info はデータベースを変更しないため、接続確認やデプロイ前の確認に向いています。

マイグレーションを検証する

validate は、データベースに記録されたマイグレーションと、現在のファイルを比較します。

flyway -environment=local validate

適用済みのバージョン済みマイグレーションを後から編集するとチェックサムが変わり、validate が失敗します。これは、適用済みの変更が書き換えられたことを検出するための安全装置です。

マイグレーションを実行する

migrate を実行すると、未適用のマイグレーションがバージョン順に適用されます。

flyway -environment=local migrate

Flywayは必要に応じて flyway_schema_history テーブルを作成し、各マイグレーションのバージョン、説明、チェックサム、適用日時などを記録します。

適用後にもう一度 info を実行すると、V1 と V2 が成功済みとして表示されます。

flyway -environment=local info

よく使うコマンド

コマンド	用途
`info`	マイグレーションの状態を確認する
`validate`	適用済みファイルとの不一致を検証する
`migrate`	未適用のマイグレーションを実行する
`baseline`	既存データベースを指定バージョンから管理対象にする
`repair`	スキーマ履歴のメタデータを修復する
`clean`	管理対象のオブジェクトを削除する。通常はローカル専用

clean はテーブルなどを削除する破壊的なコマンドです。本番環境では無効化し、誤操作できないようにします。

既存データベースへ後からFlywayを導入する場合は、いきなり全履歴を実行するのではなく、対象データベースの現状を確認したうえで baseline を使うことがあります。導入時の基準バージョンは、チームで合意してから決めましょう。

うまく動かないときの確認順

`No database found to handle ...` と表示される

JDBC URLに対応するFlywayのデータベースモジュール、またはJDBCドライバーが不足している可能性があります。Flywayの配布物に含まれているか、drivers/ に追加されているかを確認します。

マイグレーションが見つからない

次を確認します。

locations のパスが、実行時の作業ディレクトリから見て正しいか
ファイル名が V1__create_users.sql のような規則に従っているか
大文字・小文字や拡張子が正しいか
対象の環境を -environment=local で選択しているか

`validate` が失敗する

適用済みのバージョン済みマイグレーションを編集していないか確認します。共有環境ですでに適用されたファイルは元に戻し、必要な変更を新しいバージョンのSQLとして追加するのが基本です。

設定値が想定と違う

設定ファイル、環境変数、コマンドライン引数のどこから値が読み込まれているかを確認します。詳細ログが必要な場合は -X を付けて実行します。

flyway -environment=local -X info

まとめ

Flyway CLIの基本的な流れは次のとおりです。

flyway.toml で環境とマイグレーションの場所を設定する
V1__...sql のようなファイルを作成する
info で状態を確認する
validate で不一致がないことを確認する
migrate で未適用の変更を実行する

重要なのは、適用済みのマイグレーションを書き換えず、データベースの変更を新しいSQLファイルとして積み上げることです。

次に読む記事

CLIでの実行を確認したら、ファイル名と実行順のルール、アプリケーションへの組み込み方を確認できます。

Flywayのバージョンや実行順の管理方法 VとRの違い、命名規則、適用済みSQLを変更しない運用を確認する

Gradleを用いたFlywayのセットアップ方法 Gradleタスクで実行する方法と、Spring Boot起動時に実行する方法を比較する

参考：