Java Flywayとは？データベースのバージョン管理を楽にするマイグレーションツール

Java

Javaでアプリケーションを開発していると、データベースの構造を変更する機会が何度も訪れます。

「新しいテーブルを追加したい」「カラムの名前を変更したい」「本番環境と開発環境でデータベースの状態がずれてしまった」…こんな経験はありませんか？

Flyway（フライウェイ）は、こうしたデータベースの変更を安全に、確実に管理できるツールです。

この記事では、Flywayの基本から実際の使い方まで、初心者の方にも分かりやすく解説していきます。

スポンサーリンク

Flywayとは？基本を理解しよう

まずは、Flywayがどんなツールなのか見ていきましょう。

Flywayの概要

Flywayは、データベースマイグレーションツールの一つです。

マイグレーションというのは、データベースの構造を変更することを指します。テーブルの追加や削除、カラムの変更などが該当しますね。

Flywayを使うと、こうした変更を履歴として管理しながら、段階的にデータベースを更新できるんです。

データベースマイグレーションの課題

Flywayを使わない場合、こんな問題が起きやすくなります。

手動でのSQL実行はミスが起きやすい
本番環境で手作業でSQLを実行すると、実行し忘れや順序のミスが発生します。

環境間の差異が生まれる
開発環境、テスト環境、本番環境でデータベースの状態がバラバラになってしまいます。

変更履歴が残らない
「いつ誰がどんな変更をしたか」が分からなくなります。

Flywayは、これらの問題を解決してくれる強力なツールなんです。

Flywayの特徴

Flywayには、こんな特徴があります。

特徴説明
シンプルSQLファイルを書くだけで使える
自動化アプリケーション起動時に自動でマイグレーション実行
バージョン管理どのマイグレーションが実行済みか記録される
ロールバック対応有料版では変更を戻すこともできる
多様なDB対応MySQL、PostgreSQL、Oracleなど主要DBをサポート

Flywayの仕組み

Flywayがどのように動作するのか、基本的な仕組みを理解しましょう。

マイグレーションファイル

Flywayでは、データベースの変更内容をマイグレーションファイルに記述します。

これは普通のSQLファイルで、ファイル名に決まったルールがあります。

V1__Create_user_table.sql
V2__Add_email_column.sql
V3__Create_product_table.sql

ファイル名の構成は以下の通りです。

  • V：バージョンを示す接頭辞（必須）
  • 1、2、3：バージョン番号（連番または数値）
  • __：アンダースコア2つ（区切り文字）
  • Create_user_table：説明文（分かりやすい名前をつける）
  • .sql：拡張子

スキーマ履歴テーブル

Flywayは、データベース内にflyway_schema_historyという特別なテーブルを自動的に作成します。

このテーブルには、以下の情報が記録されます。

  • どのマイグレーションが実行されたか
  • いつ実行されたか
  • 実行にかかった時間
  • 実行が成功したか失敗したか

この履歴を見れば、データベースが今どの状態にあるのか一目で分かるんです。

マイグレーションの実行フロー

Flywayは、こんな流れでマイグレーションを実行します。

  1. マイグレーションファイルを読み込む
  2. flyway_schema_historyテーブルで実行済みのマイグレーションを確認
  3. 未実行のマイグレーションを番号順に実行
  4. 実行結果をflyway_schema_historyに記録

すでに実行済みのマイグレーションは、再度実行されることはありません。

Flywayのセットアップ方法

それでは、実際にJavaプロジェクトでFlywayを使う方法を見ていきましょう。

Maven プロジェクトでの導入

Mavenの場合は、pom.xmlに依存関係を追加します。

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>9.22.3</version>
</dependency>

Mavenというのは、Javaプロジェクトのライブラリを管理するツールのことです。

Gradle プロジェクトでの導入

Gradleを使っている場合は、build.gradleに以下を追加します。

dependencies {
    implementation 'org.flywaydb:flyway-core:9.22.3'
}

Gradleも、Mavenと同じくライブラリ管理ツールの一つです。

Spring Boot での設定

Spring Bootを使っている場合は、application.propertiesまたはapplication.ymlで設定を行います。

application.propertiesの例

spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=root
spring.datasource.password=password
spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration

設定項目の説明

  • spring.datasource.url：データベースの接続先
  • spring.flyway.enabled：Flywayを有効化するかどうか
  • spring.flyway.locations：マイグレーションファイルの配置場所

Spring Bootでは、依存関係を追加するだけで自動的にFlywayが動作します。便利ですね。

マイグレーションファイルの作成

実際にマイグレーションファイルを作ってみましょう。

ファイルの配置場所

マイグレーションファイルは、プロジェクト内の決まった場所に配置します。

src/main/resources/db/migration/

このディレクトリに、SQLファイルを作成していきます。

最初のマイグレーション

ユーザーテーブルを作成する例を見てみましょう。

ファイル名：V1__Create_users_table.sql

CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

このファイルを配置するだけで、Flyway実行時に自動的にテーブルが作成されます。

カラムを追加するマイグレーション

既存のテーブルにカラムを追加する例です。

ファイル名：V2__Add_phone_to_users.sql

ALTER TABLE users ADD COLUMN phone VARCHAR(20);

ALTER TABLEは、既存のテーブルの構造を変更するSQL文です。

インデックスを追加するマイグレーション

検索パフォーマンスを向上させるために、インデックスを追加する例です。

ファイル名：V3__Add_index_to_email.sql

CREATE INDEX idx_users_email ON users(email);

インデックスは、データベースの検索を高速化するための仕組みです。

複数の変更を含むマイグレーション

1つのマイグレーションファイルに、複数のSQL文を含めることもできます。

ファイル名：V4__Create_products_and_orders.sql

CREATE TABLE products (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    price DECIMAL(10, 2) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE orders (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    user_id BIGINT NOT NULL,
    product_id BIGINT NOT NULL,
    quantity INT NOT NULL,
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (product_id) REFERENCES products(id)
);

関連する変更は、1つのファイルにまとめると管理しやすくなります。

Flywayの実行方法

マイグレーションファイルを作成したら、実際に実行してみましょう。

Spring Boot での自動実行

Spring Bootを使っている場合、アプリケーション起動時に自動的にFlywayが実行されます。

mvn spring-boot:run

または

gradle bootRun

このコマンドでアプリケーションを起動すると、未実行のマイグレーションが自動的に適用されます。

コマンドラインでの実行

Flywayは、コマンドラインツールとしても使えます。

Mavenプラグインを使う場合

mvn flyway:migrate

Gradleプラグインを使う場合

gradle flywayMigrate

これらのコマンドで、マイグレーションを手動で実行できます。

プログラムから実行

Javaコード内で、プログラム的にFlywayを実行することもできます。

import org.flywaydb.core.Flyway;

public class DatabaseMigration {
    public static void main(String[] args) {
        Flyway flyway = Flyway.configure()
            .dataSource("jdbc:mysql://localhost:3306/mydb", "root", "password")
            .locations("classpath:db/migration")
            .load();

        flyway.migrate();
    }
}

この方法は、特定のタイミングでマイグレーションを実行したい場合に便利です。

Flywayの便利なコマンド

Flywayには、マイグレーション以外にも便利なコマンドがあります。

info：状態確認

現在のマイグレーションの状態を確認できます。

mvn flyway:info

実行すると、以下のような情報が表示されます。

  • どのマイグレーションが実行済みか
  • どのマイグレーションが未実行か
  • 各マイグレーションの実行日時

validate：検証

マイグレーションファイルと実際のデータベースの状態が一致しているか検証します。

mvn flyway:validate

本番環境にデプロイする前に、検証を行うと安心です。

clean：クリーンアップ

データベース内のすべてのオブジェクトを削除します。

mvn flyway:clean

注意：このコマンドは非常に危険です。すべてのテーブルやデータが削除されるので、開発環境でのみ使用してください。

repair：修復

flyway_schema_historyテーブルの状態を修復します。

mvn flyway:repair

マイグレーションが失敗した場合などに使用します。

ベストプラクティスと注意点

Flywayを効果的に使うためのポイントをまとめました。

マイグレーションファイルは追加のみ

一度作成したマイグレーションファイルは、絶対に変更してはいけません。

もし間違いに気づいたら、新しいマイグレーションファイルを作成して修正します。

悪い例

V1__Create_users.sql を修正する（NG）

良い例

V2__Fix_users_table.sql を新規作成する（OK）

バージョン番号の付け方

バージョン番号は、連番にするのが一般的です。

V1__初期テーブル作成.sql
V2__カラム追加.sql
V3__インデックス追加.sql

または、日付を使う方法もあります。

V20240101__初期テーブル作成.sql
V20240102__カラム追加.sql

チーム内で統一したルールを決めておきましょう。

実行前のバックアップ

本番環境でマイグレーションを実行する前は、必ずデータベースのバックアップを取りましょう。

万が一問題が起きても、バックアップがあれば復旧できます。

テスト環境での事前確認

本番環境で実行する前に、テスト環境で必ず動作確認を行ってください。

マイグレーションが正常に完了するか、アプリケーションが問題なく動作するか確認します。

ロールバックの考慮

Flywayの無料版では、ロールバック機能がありません。

そのため、変更を戻す必要がある場合は、手動でロールバック用のマイグレーションを作成する必要があります。

-- V5__Undo_add_phone_column.sql
ALTER TABLE users DROP COLUMN phone;

トラブルシューティング

Flywayを使う際によく遭遇する問題と、その解決方法です。

マイグレーションが実行されない

症状
アプリケーションを起動しても、マイグレーションが実行されない。

原因と対処法

  1. Flywayが無効になっている
    application.propertiesでspring.flyway.enabled=trueを確認
  2. ファイル名が間違っている
    Vで始まっているか、アンダースコアが2つあるか確認
  3. ファイルの配置場所が間違っている
    src/main/resources/db/migration/に配置されているか確認

マイグレーションが失敗する

症状
マイグレーション実行時にエラーが発生する。

対処法

  1. エラーメッセージを確認
    SQL構文エラーがないかチェック
  2. 状態を修復
    flyway:repairコマンドを実行して履歴テーブルを修復
  3. 手動で修正
    必要に応じて、データベースを手動で修正してから再実行

チェックサムエラー

症状
「Checksum mismatch」というエラーが表示される。

原因
実行済みのマイグレーションファイルが変更された。

対処法
マイグレーションファイルを元に戻すか、flyway:repairで履歴を修復します。

本番環境と開発環境で状態が異なる

症状
環境によってマイグレーションの実行状態が違う。

対処法

  1. infoコマンドで確認
    各環境の状態を確認して差異を特定
  2. 不足分を実行
    未実行のマイグレーションを順番に実行
  3. 環境を再構築
    必要に応じて、環境をクリーンな状態から構築し直す

まとめ

Java Flywayについて解説してきました。

重要なポイント

  • Flywayはデータベースマイグレーションを管理するツール
  • マイグレーションファイルはSQLで記述し、バージョン管理される
  • Spring Bootでは自動的にマイグレーションが実行される
  • 一度作成したマイグレーションファイルは変更してはいけない
  • 本番環境での実行前は必ずバックアップとテスト環境での確認を行う
  • flyway_schema_historyテーブルで実行履歴が管理される

Flywayを使えば、データベースの変更を安全に管理できるようになります。

最初は難しく感じるかもしれませんが、基本的な使い方はシンプルです。

まずは開発環境で試してみて、徐々に本番環境にも適用していってください。チーム全体でFlywayを使うことで、データベース管理の品質が大きく向上しますよ！

Youtube

神話・歴史・伝承の解説チャンネル

スポンサーリンク

コメント

タイトルとURLをコピーしました