FlywayでWordPressの独自テーブルを管理する手順（導入・baseline・migrate）

Flyway は、データベースの変更を V2__create_table.sql のような番号付きの SQL ファイルで管理し、どこまで適用したかを DB 内の履歴テーブルに記録するツールです。開発・検証・本番の DB に同じ変更を同じ順番で当てられるので、複数人で同じサイトを触るときの「どの環境にどの変更を入れたか分からない」を防げます。

この記事では、WordPress サイトの DB に Flyway を導入し、独自テーブルの作成と変更を管理する手順を説明します。

Flywayで管理するもの・しないもの

WordPress の DB には、管理者がすでに決まっているテーブルがあります。Flyway で触るのは、それ以外の部分だけにします。

コアやプラグインのテーブルを Flyway で変更すると、次の WordPress 本体やプラグインの更新で構造が食い違うおそれがあります。投稿やオプションの値を書き換えたいだけなら、Flyway ではなく WP-CLI（wp option update、wp search-replace など）のほうが向いています。

前提

• Linux サーバー（x64）に SSH で入れること
• WordPress の DB が MySQL または MariaDB であること
• DB ユーザーに CREATE・ALTER・INSERT などの権限があること（wp-config.php の DB_USER をそのまま使うか、マイグレーション用のユーザーを作る）
• 作業前に DB のバックアップを取っておくこと（wp db export など）

手順1: Flywayをインストールする

Flyway のコマンドライン版は、Redgate の配布サイトから tar.gz で入手できます。2026年11月時点の最新版は 13.12.1 です。公式のダウンロードページで最新の版を確認し、FLYWAY_VERSION を合わせてください。Linux x64 版の圧縮ファイルは Java の実行環境を含んでいるため、600MB ほどあります。

FLYWAY_VERSION=13.12.1
cd /opt
sudo wget "https://download.red-gate.com/maven/release/com/redgate/flyway/flyway-commandline/${FLYWAY_VERSION}/flyway-commandline-${FLYWAY_VERSION}-linux-x64.tar.gz"
sudo tar -xzf "flyway-commandline-${FLYWAY_VERSION}-linux-x64.tar.gz"
sudo ln -s "/opt/flyway-${FLYWAY_VERSION}/flyway" /usr/local/bin/flyway

# 動作確認
flyway --version

展開したディレクトリの中の drivers/ には JDBC ドライバー、conf/ には設定ファイル、sql/ にはマイグレーションの置き場所があります。この記事ではインストール先とは別に、サイトごとのプロジェクトディレクトリを作って使います。

手順2: プロジェクトと設定ファイルを作る

mkdir -p ~/flyway-wp/sql
cd ~/flyway-wp

Flyway 10 以降は TOML 形式の設定ファイルが標準です。実行するディレクトリにある flyway.toml が読み込まれます。

[environments.default]
url = "jdbc:mysql://localhost:3306/wordpress?permitMysqlScheme=true"
user = "${env.FLYWAY_DB_USER}"
password = "${env.FLYWAY_DB_PASSWORD}"

[flyway]
locations = ["filesystem:sql"]

[flyway.placeholders]
table_prefix = "wp_"

ポイントは次のとおりです。

• 接続先（url）: wordpress の部分は wp-config.php の DB_NAME に合わせます。
• JDBC ドライバー: Flyway のコマンドライン版には MySQL 公式のドライバー（Connector/J）が同梱されておらず、同梱の MariaDB ドライバーが代わりに使われます。Flyway 10.7.0 以降、この MariaDB ドライバーは jdbc:mysql:// の URL をそのままでは受け付けないため、URL に permitMysqlScheme=true を付けます。MySQL 公式のドライバーを使いたい場合は、Maven Central から Connector/J の jar を入手して drivers/ に置けば、付けなくて構いません。DB が MariaDB なら jdbc:mariadb://localhost:3306/wordpress と書けます。
• パスワード: ${env.変数名} で環境変数から読み込めます。設定ファイルにパスワードを直接書かず、Git にも入れないようにします。
• プレースホルダー: [flyway.placeholders] に書いた値は、SQL ファイルの中で ${table_prefix} のように使えます。wp-config.php の $table_prefix と同じ値にしておけば、テーブル接頭辞が wp_ でないサイトでも同じ SQL を使えます。

実行する前に環境変数を設定します。

export FLYWAY_DB_USER=wp_migrator
read -rs FLYWAY_DB_PASSWORD && export FLYWAY_DB_PASSWORD

read -rs で入力したパスワードは画面に表示されず、シェルの履歴にも残りません。

手順3: 既存のDBにbaselineを設定する

WordPress の DB にはすでにテーブルがあるため、そのまま migrate を実行すると「空でないスキーマに履歴テーブルが無い」というエラーで止まります。最初に一度だけ baseline を実行し、「今の状態を基準（バージョン1）とする」ことを Flyway に記録させます。

cd ~/flyway-wp
flyway baseline
flyway info

baseline を実行すると、DB に flyway_schema_history という履歴テーブルが作られます。WordPress には影響しませんが、DB 内に WordPress 以外のテーブルが1つ増えることは知っておいてください。

基準のバージョンが 1 なので、この後に作るマイグレーションは V2 から始めます。バージョン1以下のファイルは適用済みとみなされ、実行されません。

手順4: マイグレーションのSQLファイルを書く

SQL ファイルは sql/ に置き、V<バージョン>__<説明>.sql の形で名前を付けます。V は大文字、バージョンと説明の間はアンダースコア2つです。バージョンの数字の順に適用されます。

sql/V2__create_reservations.sql（予約を記録する独自テーブルを作る例）:

CREATE TABLE ${table_prefix}reservations (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  post_id BIGINT UNSIGNED NOT NULL,
  reserved_on DATE NOT NULL,
  name VARCHAR(191) NOT NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY post_id (post_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

sql/V3__add_status_to_reservations.sql（後から列を追加する例）:

ALTER TABLE ${table_prefix}reservations
  ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT 'pending' AFTER name;

一度適用したファイルは書き換えません。Flyway はファイルのチェックサムを履歴テーブルに記録しており、適用後に中身を変えると validate で不一致として検出されます。変更したいときは、新しい番号のファイルを追加します。

手順5: 適用して結果を確かめる

cd ~/flyway-wp
flyway info      # 未適用のマイグレーションが Pending と表示される
flyway migrate   # Pending のものを番号順に適用する
flyway info      # Success になっていることを確認する

テーブルができたかは、WP-CLI でも確認できます。

wp db query "SHOW TABLES LIKE 'wp\_reservations'" --path=/var/www/html

WordPress のテーマやプラグインから使うときは、接頭辞を $wpdb->prefix で付けます。

<?php
global $wpdb;
$table = $wpdb->prefix . 'reservations';
$rows  = $wpdb->get_results(
	$wpdb->prepare( "SELECT id, name, reserved_on FROM {$table} WHERE post_id = %d", get_the_ID() )
);

失敗したときの対処

MySQL と MariaDB では、CREATE TABLE や ALTER TABLE などの DDL はトランザクションで取り消せません。1つのファイルに複数の DDL を書いて途中で失敗すると、前半だけが適用された状態で止まります。そのため、1ファイルには1つの変更だけを書くと後始末が楽になります。

失敗した場合の流れは次のとおりです。

1. flyway info で失敗したバージョンを確認する
2. 途中まで適用された変更があれば、手で元に戻す（または残りを手で当てる）
3. SQL ファイルの誤りを直す
4. flyway repair で履歴テーブルから失敗の記録を取り除く
5. もう一度 flyway migrate を実行する

運用の注意

• 元に戻すときも前に進める: 変更を取り消したいときは、取り消す SQL を新しい番号のファイルとして追加します。本番に当てる前の DB バックアップも取っておきます。
• clean は使わない: flyway clean はスキーマ内のテーブルをすべて削除するコマンドです。WordPress のテーブルも消えます。初期設定では無効（cleanDisabled が true）になっているので、そのままにしておきます。
• ファイルは Git で管理する: sql/ と flyway.toml を Git に入れ、開発・検証・本番で同じファイルを使います。接続先の違いは環境変数で吸収します。
• 適用の順番を守る: 本番へは、検証環境で migrate が通ったものだけを当てます。

まとめ

• Flyway で管理するのはサイト独自のテーブルだけにし、コアとプラグインのテーブルには触れない
• 接続には同梱の MariaDB ドライバーを使い、MySQL の URL には permitMysqlScheme=true を付ける
• 既存の WordPress DB では最初に baseline を実行し、マイグレーションは V2 から書く
• 適用済みのファイルは書き換えず、変更は新しい番号のファイルで追加する
• 失敗したら原因を直して repair → migrate。clean は無効のままにする

関連記事:

• WP-CLIでWordPressのデータベースをエクスポートする方法
• WP-CLIのdbコマンドの使い方