Flywayのバージョンや実行順の管理方法を知りましょう

Flywayのマイグレーションファイル名には、バージョンや実行順序を認識させるための命名規則があります。

ルールを破ると、ファイルが見つからなかったり、適用済みのマイグレーションを変更したことで validate が失敗したりします。この記事では、SQLマイグレーションを運用するために知っておきたいファイル名と実行順を整理します。

ファイル名の基本形

バージョン付きマイグレーションの基本形は次のとおりです。

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

例えば、次のファイルは 1 というバージョンのマイグレーションです。

V1__create_users.sql

ファイル名は次の要素で構成されます。

プレフィックス + バージョン + 区切り文字 + 説明 + 拡張子

プレフィックスの種類

`V`：バージョン付きマイグレーション

V で始まるマイグレーションは、バージョン番号によって実行順が決まります。適用済みのバージョン付きマイグレーションは、通常は二度実行されません。

V1__create_users.sql
V2__add_points_to_users.sql

テーブル作成やカラム追加など、順番に適用するスキーマ変更には、まず V のマイグレーションを使うと分かりやすくなります。

`R`：リピータブルマイグレーション

R で始まるマイグレーションはバージョンを持ちません。ファイルのチェックサムが変わると、migrate の実行時に再適用されます。

R__create_user_view.sql
R__insert_reference_data.sql

ビュー、ストアドプロシージャ、関数など、定義を1つのファイルで管理したい場合に向いています。リピータブルマイグレーションは、保留中のバージョン付きマイグレーションが適用された後に実行されます。

再実行されることを前提に、CREATE OR REPLACE など、複数回実行しても問題が起きにくいSQLにします。

バージョン番号

バージョン番号は V と __ の間に記述します。

V1__create_users.sql
V1.1__add_email_to_users.sql
V2__create_orders.sql

. や _ で区切った数値を階層として扱えるため、1.10 は文字列順ではなく、1.2 より新しいバージョンとして扱われます。

例えば、次のファイルが同時に未適用の場合、実行順はバージョンの小さい順です。

V1.1__add_name.sql
V1.2.3__add_status.sql
V1.10__add_points.sql
V11__create_orders.sql
V2026__add_index.sql

実行順は、おおむね次のようになります。

V1.1__add_name.sql
V1.2.3__add_status.sql
V1.10__add_points.sql
V11__create_orders.sql
V2026__add_index.sql

ただし、実際の運用では表記を増やしすぎず、プロジェクト内で統一した形式を決めることが重要です。例えば、V1__...、V2__... のような単純な連番や、V20260924120000__... のようなタイムスタンプ形式を採用します。

区切り文字と説明

バージョンと説明の間には、アンダースコアを2つ置きます。

V3__add_created_at_to_users.sql

アンダースコア1つでは、ファイル名を正しく解釈できません。

説明部分は、ファイルで何を変更するのか分かる名前にします。単語の区切りには _ や空白を使えますが、プロジェクト内で形式を統一すると検索しやすくなります。

適用後の説明はスキーマ履歴テーブルにも記録されます。後からファイル名を変更すると、チェックサムや履歴との対応が分かりにくくなるため、適用済みファイルの名前も変更しないようにします。

よくある間違い

プレフィックスが小文字になっている

v1__create_users.sql

V は大文字で記述します。

区切り文字が1つしかない

V1_create_users.sql

バージョンと説明の区切りは __ です。

バージョンに文字を含めている

V1.0-beta__create_users.sql

バージョン部分には、プロジェクトで採用しているFlywayの形式に従った数値を使います。beta のような意味は説明部分へ移します。

V1.0__create_users_beta.sql

適用済みのファイルを書き換えている

すでに共有環境へ適用した V1__create_users.sql を編集すると、ファイルのチェックサムが履歴と一致しなくなります。

既存の変更を修正する場合は、元のファイルを戻したうえで、新しいバージョンのマイグレーションを追加します。

V1__create_users.sql
V2__rename_user_name.sql

実行順と履歴

Flywayはマイグレーションの適用状況を、データベース内の flyway_schema_history テーブルで管理します。

新しいマイグレーションを追加すると、Flywayはファイルのバージョンと履歴テーブルを比較して、未適用のファイルを判断します。

例えば、V1 まで適用済みの状態で V2 と V3 を追加すると、通常は次の順番で適用されます。

V1  適用済み
V2  未適用 -> 先に適用
V3  未適用 -> 次に適用

info で、適用済み・未適用・失敗したマイグレーションを確認できます。

flyway -environment=local info

後から追加した古いバージョンの扱い

通常、現在のバージョンより小さい番号のマイグレーションを後から追加しても、Flywayは自動的には適用しません。これは、共有環境へ適用済みの履歴より前に変更を差し込む事故を防ぐためです。

意図的に順不同のマイグレーションを許可する outOfOrder 設定もありますが、適用順が環境ごとに変わる可能性があるため、常用は避けます。基本は、現在の最新バージョンより大きい番号で新しいマイグレーションを追加します。

運用ルール

チームでFlywayを使うときは、次のルールを決めておくと安全です。

適用済みのバージョン付きマイグレーションを編集しない
新しい変更は、現在の最新バージョンより大きい番号で追加する
バージョンの形式と説明の命名規則をプロジェクト内で統一する
CI/CDでは validate を実行して、適用済みファイルの変更を検出する
R のマイグレーションは、何度実行しても壊れないSQLにする

flyway -environment=local validate
flyway -environment=local migrate

まとめ

Flywayのファイル名と実行順で、特に重要なのは次の点です。

V<バージョン>__<説明>.sql がバージョン付きマイグレーションの基本形
R__<説明>.sql はチェックサムが変わると再実行される
バージョンは文字列ではなく、数値の階層として比較される
適用済みファイルは変更せず、新しいバージョンのファイルを追加する
実行順や適用状況は flyway_schema_history と info で確認する

命名規則をチームで統一し、適用済みのSQLを変更しない運用にすると、環境ごとのスキーマ差分を追跡しやすくなります。

参考：