今回は「Flywayの使い方」についてまとめます。
Flywayとは
「データベースのスキーマに対してバージョン管理するツール」
アプリのソースコードはsvnやgitといった仕組みでバージョン管理されてきましたが、データベースに対してはそういったバージョン管理の仕組みがありませんでした。 Flywayではその「データベースのスキーマ」に対するバージョン管理を実現する仕組みになります。
ツールはコマンドライン、JavaAPI、Mavenプラグイン、Gradleプラグインに対応しています。 今回はコマンドラインツールの使い方を見ていきます。
対応する主要なRDBは以下の通りです。 ほとんど対応しているような印象です。
- Oracle
- SQL Server
- DB2
- MySql
- MariaDB
- PostgreSQL
- SQLite
インストール
Flyway は Javaプログラム なので Java実行環境 が必要になります。 まだインストールしていないようであれば、OracleのサイトからJREをダウンロードしてインストールします。
基本的には Flyway のサイトにあるリソースをダウンロードしてローカルに展開するだけです。
Linuxだけ /usr/local/bin へシンボリックリンクを追加する必要があるようですが、Windows と mac は解凍すればそのまま使えるみたいです。
ダウンロード先は以下です。
Flywayのリソースを解凍したときのフォルダ構造は以下のようになっています。 「実行ファイル」「設定ファイル」「SQLマイグレーションファイルの配置先」の3か所おさえておけばOKです。
flyway-x.x.x │ flyway ←mac/linux用の実行ファイル │ flyway.cmd ←windows用の実行ファイル │ ├─conf │ flyway.conf ←設定ファイル │ ├─jars ←Javaマイグレーションを行う場合の配置先フォルダ │ ├─sql ←SQLマイグレーションを行う場合の配置先フォルダ │ ├─drivers ┐ ├─jre ｜Flyway本体および関連するファイル群。 ├─lib ｜ └─licenses ┘
初期設定
Flywayはスキーマ管理したいデータベースに接続し「Flyway管理用のテーブル」を作成してデータベースのバージョン管理を行います。 そのため、あらかじめ管理したいデータベースへ接続する情報を flyway.conf に設定しておくと便利です。 パスワードなど保存したくない場合など、コマンド実行時に引数で渡すことで flyway.conf の設定を上書きすることも可能です。
/conf/flyway.conf
# 接続情報 flyway.url=jdbc:mysql://172.17.0.3:3306/sample flyway.user=user flyway.password=Passw0rd flyway.schemas=sample # マイグレーションファイル配置先 # 別の場所を指定したい場合に利用する flyway.locations=/sql/**/* # 更新履歴の保存先テーブル名 flyway.table=z_schema_history
データベースの状態確認
上記設定が終わればデータベースへ接続確認してみます。
flyway infoコマンドで現在の状態（スキーマバージョンの適用履歴）を表示できます。
[root@bc33ac5c9624 /]# flyway info Flyway Community Edition 6.4.4 by Redgate Database: jdbc:mysql://172.17.0.3:3306/sample (MySQL 5.7) Schema version: << Empty Schema >> +----------+---------+-------------+------+--------------+-------+ | Category | Version | Description | Type | Installed On | State | +----------+---------+-------------+------+--------------+-------+ | No migrations found | +----------+---------+-------------+------+--------------+-------+
初回だとまだ何も設定されちないので No migrations found のメッセージが表示されます。
ベースラインの作成
スキーマのバージョン管理を始めるため、flyway baseline コマンドで初期状態を設定します。
[root@bc33ac5c9624 /]# flyway baseline Flyway Community Edition 6.4.4 by Redgate Database: jdbc:mysql://172.17.0.3:3306/sample (MySQL 5.7) Creating Schema History table `sample`.`flyway_schema_history` with baseline ... Successfully baselined schema with version: 1
うまくベースラインが作成できていれば、 flyway info を実行した際、以下のような表示になります。
[root@8c0ab63e8ddb /]# flyway info Flyway Community Edition 6.4.4 by Redgate Database: jdbc:mysql://172.17.0.3:3306/sample (MySQL 5.7) Schema version: 1 +----------+---------+-----------------------+----------+---------------------+----------+ | Category | Version | Description | Type | Installed On | State | +----------+---------+-----------------------+----------+---------------------+----------+ | | 1 | << Flyway Baseline >> | BASELINE | 2020-06-27 08:23:39 | Baseline | +----------+---------+-----------------------+----------+---------------------+----------+
マイグレーションの実行
ベースラインまでできていれば、ようやくここからスキーマバージョン管理を行っていくことになります。
基本はデータベースを修正するSQLを作成、SQLファイルは決められた命名規則でファイル名を設定し、決められた場所へ配置、その後、 flyway migrate でデータベース更新になります。
create文だけ作っていれば、あとは自動的に差分を検出、移行用のSQL作成/適用してくれる…かと思ってましたが、そんなに高度ではないようです。 結局、データベースを修正する場合、データベースを移行するSQLをきちんと手動で作成しなければいけません。 もちろん切り戻し発生したら、切り戻し用のSQLが必要です。
マイグレーションの種類
マイグレーションには以下の3種類があります。 今回は Versioned Migration だけ取り上げます。
- Versioned Migration
- Undo Migration
- Repeat Migration
Versioned Migration は通常のスキーマバージョンを前方へ進めるマイグレーション処理になります。 テーブルの追加/削除/変更、データの追加/削除/更新などで利用します。 その名の通り、バージョン番号を持ちます。
Undo Migration は Versioned Migration を取り消すマイグレーション処理になります。 ただ…この機能は Pro版 でないと利用できないので Community版 だと使えません。
Repeat Migration は毎マイグレーション処理で実行される処理になります。
SQLファイルの準備
ファイル作成
まずは以下の命名規則に従ってSQLファイルを作成します。
- prefix
"V"で Versioned Migration 、"U"で Undo Migration 、"R"で Repeat Migration を示します。- version
- バージョン番号は一意になるように設定します。
"."(ピリオド)で区切る文字列で定義します。 通常は整数で定義するようです。 以下のようなバージョン文字列が利用可能です。- 1
- 001
- 1.2.3
- 20200627
- 2020.06.27
- separator
"__"(アンダースコア2つ)固定です。- description
- 該当バージョンの修正概要を記載します。
文字は
" "(空白)または"_"(アンダースコア)で結合します。 - suffix
".sql"固定です。
ファイル配置
作成したファイルは以下の flyway を解凍して展開したフォルダ配下にある /sql 以下へ配置します。
flyway-x.x.x │ flyway ←mac/linux用の実行ファイル │ flyway.cmd ←windows用の実行ファイル │ └─sql ←SQLマイグレーションを行う場合の配置先フォルダ
マイグレーションの実行
ファイル配置まで終われば flyway info でデータベースとの差分が検知されるようになります。
以下の例では V2__add_user.sql というファイルを作成したケースでの表示になります。
データベースには未適用なので State は Pending になっています。
[root@8c0ab63e8ddb sql]# flyway info Flyway Community Edition 6.4.4 by Redgate Database: jdbc:mysql://172.17.0.2:3306/sample (MySQL 5.7) Schema version: 1 +-----------+---------+-----------------------+----------+---------------------+----------+ | Category | Version | Description | Type | Installed On | State | +-----------+---------+-----------------------+----------+---------------------+----------+ | | 1 | << Flyway Baseline >> | BASELINE | 2020-06-27 08:23:39 | Baseline | | Versioned | 2 | add user | SQL | | Pending | +-----------+---------+-----------------------+----------+---------------------+----------+
この状態で、 flyway migrate を実行するとデータベースに対して更新処理が実行されます（= 配置したSQLが実行されます）。
[root@8c0ab63e8ddb sql]# flyway migrate Flyway Community Edition 6.4.4 by Redgate Database: jdbc:mysql://172.17.0.2:3306/sample (MySQL 5.7) Successfully validated 2 migrations (execution time 00:00.024s) Current version of schema `sample`: 1 Migrating schema `sample` to version 2 - add user Successfully applied 1 migration to schema `sample` (execution time 00:00.088s)
実行後に再度 flyway info を実行すると、 State が Success に変わっていることが確認できます。
[root@8c0ab63e8ddb sql]# flyway info Flyway Community Edition 6.4.4 by Redgate Database: jdbc:mysql://172.17.0.2:3306/sample (MySQL 5.7) Schema version: 2 +-----------+---------+-----------------------+----------+---------------------+----------+ | Category | Version | Description | Type | Installed On | State | +-----------+---------+-----------------------+----------+---------------------+----------+ | | 1 | << Flyway Baseline >> | BASELINE | 2020-06-27 08:23:39 | Baseline | | Versioned | 2 | add user | SQL | 2020-06-27 12:31:30 | Success | +-----------+---------+-----------------------+----------+---------------------+----------+
失敗した場合の再実行
もし、SQLに誤りがあり、データベースの更新に失敗した場合、以下のように Status が Failed の表示になります。
[root@8c0ab63e8ddb sql]# flyway info Flyway Community Edition 6.4.4 by Redgate Database: jdbc:mysql://172.17.0.2:3306/sample (MySQL 5.7) Schema version: 2 +-----------+---------+-----------------------+----------+---------------------+----------+ | Category | Version | Description | Type | Installed On | State | +-----------+---------+-----------------------+----------+---------------------+----------+ | | 1 | << Flyway Baseline >> | BASELINE | 2020-06-27 12:21:39 | Baseline | | Versioned | 2 | add user | SQL | 2020-06-27 12:22:45 | Failed | +-----------+---------+-----------------------+----------+---------------------+----------+
この場合、一度 flyway repair を実行してSQL実行自体をなかったことにし、SQLを修正して再度 flyway migrate を行います。
[root@8c0ab63e8ddb sql]# flyway repair Flyway Community Edition 6.4.4 by Redgate Database: jdbc:mysql://172.17.0.2:3306/sample (MySQL 5.7) Successfully repaired schema history table `sample`.`z_schema_history` (execution time 00:00.040s).
[root@8c0ab63e8ddb sql]# flyway info Flyway Community Edition 6.4.4 by Redgate Database: jdbc:mysql://172.17.0.2:3306/sample (MySQL 5.7) Schema version: 1 +-----------+---------+-----------------------+----------+---------------------+----------+ | Category | Version | Description | Type | Installed On | State | +-----------+---------+-----------------------+----------+---------------------+----------+ | | 1 | << Flyway Baseline >> | BASELINE | 2020-06-27 12:21:39 | Baseline | | Versioned | 2 | add user | SQL | | Pending | +-----------+---------+-----------------------+----------+---------------------+----------+
今回は「Flywayの使い方」についてまとめました。 参考になったでしょうか？ 本記事がお役に立っていると嬉しいです！！