今回は「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ファイルを作成します。
- 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の使い方」についてまとめました。
参考になったでしょうか?
本記事がお役に立っていると嬉しいです!!