Flyway を用いた初期データの挿入

January 08, 2022 omuomugin 日記

TL;DR

Flyway の Repeatable Migrations を初期データを挿入したいときにだけマイグレーションファイルの対象にコピーすれば flyway migrate の際に自動で適用される。

Flyway とは？

Flyway は、データベースのマイグレーションツールで特にバージョン管理に着目したツールになっている。
以下のように V1.x__XXXX のようなバージョン番号が prefix についた sql ファイルを用意することでバージョン番号通りにマイグレーションを適用して行ってくれる。

.
└── migrations
    ├── V1.1__Create_Table.sql
    ├── V1.2__XXXXXX.sql
    ├── V1.3__XXXXXX.sql
    ├── V1.4__XXXXXX.sql
    └── V1.5__XXXXXX.sql

# 実行はこれだけ
flyway migrate

また、以下のような便利なコマンドも用意されている

flyway clean # データベースをまっさらの状態にする
flyway info # 現状適用されているマイグレーションの情報などを表示する

今回は、テスト環境などでの初期データを Flyway を活用して挿入する方法を紹介する。

Flyway が扱えるマイグレーションの種類

Flyway Documentation - migrations にも紹介されているように Flyway が扱うマイグレーションには、3種類ある。

Versioned Migrations
Undo Migrations
Repeatable Migrations

全てのマイグレーションは、以下のような命名規則があるのでそれに従う (命名規則を設定ファイルでカスタマイズすることもできる) ただし、Repeatable Migrations にはバージョンの概念がない (後述を参照)

<Prefix><Version>__<Description>.sql

Versioned Migrations

Versioned Migrations は、上記にも書いたように V1.x__XXXX のような形式で書いたマイグレーションファイルで prefix に付与したバージョンの番号の順番通りに適用されるようなマイグレーションファイルのことである。

Versioned Migrations のファイル名は、 prefix は V を利用して以下のような命名になる。

# <Prefix><Version>__<Description>.sql
# e.g V2__Add_new_table.sql

Undo Migrations

基本的には、後方互換性が失われてしまうので推奨されないマイグレーション。
何かのマイグレーションを取り消すような場合に用意する。

Undo Migrations のファイル名は、 prefix は U を利用して以下のような命名になる。

# <Prefix><Version>__<Description>.sql
# e.g U2__Add_new_table.sql

Repeatable Migrations

Repeatable migrations have a description and a checksum, but no version. Instead of being run just once, they are (re-)applied every time their checksum changes.

とあるように「何回でも適用可能 (冪等性を持つ) 」なマイグレーションファイルの種類。
View テーブルを作ったりなどが想定されているユースケースになっている。この種別はバージョンを持たないため順不同 (実際には description のアルファベット順ではあるはず) に実行されるので順番を意識しないマイグレーションファイルに設計する必要がある。

Repeatable Migrations のファイル名は、 prefix は R を利用して以下のような命名になる。 (全て独立して繰り返し適用可能であるためバージョンが存在しないことに注意)

# <Prefix><Version>__<Description>.sql
# e.g R__Add_new_table.sql

初期データの挿入するために

さて本題に入るが、今回は Repeatable Migrations を利用して初期データを挿入するようにしている。
Flyway の仕組みとして上記のマイグレーションのファイルたちをある特定のディレクトリ内に配置することで自動で検出させる作りになっている。

# migrations/ を指定している場合には、この配下のマイグレーションファイルが
# `flyway migrate` の際に自動で検出されて全てバージョン番号通りの順番で適用される。
.
└── migrations
    ├── V1.1__Create_Table.sql
    ├── V1.2__XXXXXX.sql
    ├── V1.3__XXXXXX.sql
    ├── V1.4__XXXXXX.sql
    ├── V1.5__XXXXXX.sql
    └── R__Test_Seed.sql # <- 初期データ挿入時には、ここにコピーする

ここに、初期データ挿入を記述した Repeatable Migrations を初期データを挿入する時にだけ、このディレクトリにコピーして flyway migrate を実行するだけで良い。