Flywayの使い方

2020年6月27日 22:06 0 件のコメント

今回は「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です。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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

?
1
2
3
4
5
6
7
8
9
10
11
12
# 接続情報
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コマンドで現在の状態（スキーマバージョンの適用履歴）を表示できます。

?
1
2
3
4
5
6
7
8
9
10
[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 コマンドで初期状態を設定します。

?
1
2
3
4
5
[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 を実行した際、以下のような表示になります。

?
1
2
3
4
5
6
7
8
9
10
[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 以下へ配置します。

?
1
2
3
4
5
flyway-x.x.x
│  flyway            ←mac/linux用の実行ファイル
│  flyway.cmd        ←windows用の実行ファイル
│ 
└─sql               ←SQLマイグレーションを行う場合の配置先フォルダ

マイグレーションの実行

ファイル配置まで終われば flyway info でデータベースとの差分が検知されるようになります。 以下の例では V2__add_user.sql というファイルを作成したケースでの表示になります。 データベースには未適用なので State は Pending になっています。

?
1
2
3
4
5
6
7
8
9
10
11
[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が実行されます）。

?
1
2
3
4
5
6
7
[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 に変わっていることが確認できます。

?
1
2
3
4
5
6
7
8
9
10
11
[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 の表示になります。

?
1
2
3
4
5
6
7
8
9
10
11
[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 を行います。

?
1
2
3
4
[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).
?
1
2
3
4
5
6
7
8
9
10
11
[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の使い方」についてまとめました。 参考になったでしょうか？ 本記事がお役に立っていると嬉しいです！！

最後に… このブログに興味を持っていただけた方は、 ぜひ 「Facebookページ に いいね！」または 「Twitter の フォロー」 お願いします！！