エンジニアの皆さん、こんにちは。テックリードの私だ。
コードレビューの際、プラグインやカスタムテーマのアップデート処理を見ていて、背筋が凍るような実装に遭遇したことはないだろうか？
// 最悪なアンチパターン：全リクエストでテーブル存在確認とALTER TABLEを実行している
global $wpdb;
$wpdb->query(“CREATE TABLE IF NOT EXISTS {$wpdb->prefix}my_custom_table (…)”);
$wpdb->query(“ALTER TABLE {$wpdb->prefix}my_custom_table ADD COLUMN extra_data VARCHAR(255)”);
毎HTTPリクエスト、あるいは`admin_init`のたびにこんなクエリを走らせているとしたら、データベースのメタデータロック（Metadata Locking）によるスループット低下を自ら引き起こしているようなものだ。InnoDBのスキーマ変更は重い。それをスケールするWordPressのライフサイクルの中で安易に実行してはならない。
今回は、プロダクション環境で耐えうる「WordPressにおけるデータベーススキーマ変更の自動マイグレーション管理」の極意を伝授する。LaravelのMigrationsやRailsのActive Record Migrationsに匹敵する、堅牢かつ洗練されたバージョン管理システムをWordPress上で構築する方法を見ていこう。
—
なぜWordPressのDBマイグレーションには「厳格なバージョン管理」が必要なのか
WordPressには、コアのデータベースバージョンを管理する `$wp_db_version` や `wp_set_wp_db_version()` という素晴らしいメカニズムが `wp-includes/version.php` や `upgrade.php` に存在する。しかし、サードパーティのプラグインやカスタムテーマにおいては、この仕組みが標準化されていない。
実務で直面する課題は主に以下の3点だ：
1. べき等性（Idempotency）の担保: 何度同じマイグレーションスクリプトが走っても、データやスキーマが壊れないこと。
2. 順序保証（Sequential Execution）: 複数開発者でのコンフリクトを防ぎ、必ず時系列順にマイグレーションが適用されること。
3. アトミック性とエラーハンドリング: スキーマ変更途中で失敗した際のロールバック（あるいは安全な中断）と、不整合状態の検知。
これらを解決する設計パターンをコードで示そう。
—
プロダクション品質のマイグレーション管理クラス
以下のコードは、プラグインの有効化時やアップデート時にのみ実行され、独自のマイグレーション履歴テーブル（`{$wpdb->prefix}schema_migrations`）に基づいて、未適用のスキーマ変更のみを安全に順次適用する堅牢なクラスだ。
/
namespace Enterprise\Database;
if ( ! defined( ‘ABSPATH’ ) ) {
exit;
}
/
- Class MigrationManager
- データベーススキーマの変更履歴を追跡し、順序保証とべき等性を持って適用する。
/
class MigrationManager {
private $wpdb;
private $table_name;
private $migrations_path;
public function __construct() {
global $wpdb;
$this->wpdb = $wpdb;
$this->table_name = $wpdb->prefix . ‘schema_migrations’;
$this->migrations_path = plugin_dir_path( __FILE__ ) . ‘migrations/’;
// フックの登録（プラグイン有効化時にスキーマ管理テーブルを初期化）
register_activation_hook( __FILE__, [ $this, ‘init_migration_table’ ] );
// 管理画面初期化時にマイグレーションチェックを実行（本番ではWP-CLIやデプロイパイプラインでの実行を推奨）
add_action( ‘admin_init’, [ $this, ‘run_pending_migrations’ ] );
}
/
- マイグレーション管理用テーブルの作成
/
public function init_migration_table() {
$charset_collate = $this->wpdb->get_charset_collate();
$sql = “CREATE TABLE IF NOT EXISTS {$this->table_name} (
id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
version VARCHAR(255) NOT NULL,
executed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (id),
UNIQUE KEY version_idx (version)
) {$charset_collate};”;
require_once( ABSPATH . ‘wp-admin/includes/upgrade.php’ );
dbDelta( $sql );
}
/
- 未適用のマイグレーションを検出し、トランザクション安全に実行する
/
public function run_pending_migrations() {
// 多重実行を防ぐためのトランジェントロック（分散環境を考慮）
$lock_key = ‘enterprise_db_migrating’;
if ( get_transient( $lock_key ) ) {
return;
}
set_transient( $lock_key, true, 30 ); // 30秒間ロック
try {
$this->init_migration_table();
$applied = $this->get_applied_migrations();
$files = $this->get_migration_files();
foreach ( $files as $version => $filepath ) {
if ( ! in_array( $version, $applied, true ) ) {
$this->execute_migration( $version, $filepath );
}
}
} catch ( \Exception $e ) {
error_log( ‘[Migration Error] ‘ . $e->getMessage() );
} finally {
delete_transient( $lock_key );
}
}
/
- 適用済みマイグレーションのバージョン一覧を取得
/
private function get_applied_migrations() {
$results = $this->wpdb->get_col( “SELECT version FROM {$this->table_name} ORDER BY id ASC” );
return $results ? $results : [];
}
/
- マイグレーションファイル群のスキャンとソート
/
private function get_migration_files() {
if ( ! is_dir( $this->migrations_path ) ) {
return [];
}
$files = glob( $this->migrations_path . ‘.php’ );
$migrations = [];
foreach ( $files as $file ) {
// ファイル名規則: YYYYMMDDHHMMSS_description.php
$filename = basename( $file, ‘.php’ );
if ( preg_match( ‘/^(\d{14})_(.+)$/’, $filename, $matches ) ) {
$version = $matches[1];
$migrations[ $version ] = $file;
}
}
// バージョン（タイムスタンプ）順にソート
ksort( $migrations );
return $migrations;
}
/
- 単一のマイグレーションを実行し、履歴に記録
/
private function execute_migration( $version, $filepath ) {
// トランザクション開始（MySQLのInnoDBかつトランザクション対応ストレージ前提）
// ※ 注意: ALTER TABLEなどのDDL文はMySQLでは暗黙のコミット（Implicit Commit）を引き起こすため、
// DDLを含む場合はdbDeltaや例外処理によるガードが必須となる。
include_once $filepath;
$class_name = $this->get_migration_class_name( $filepath );
if ( class_exists( $class_name ) ) {
$migration = new $class_name();
if ( method_exists( $migration, ‘up’ ) ) {
$migration->up();
}
}
// 適用済みとして記録
$this->wpdb->insert(
$this->table_name,
[ ‘version’ => $version ],
[ ‘%s’ ]
);
}
/
- ファイル名からクラス名を動的解決
/
private function get_migration_class_name( $filepath ) {
$filename = basename( $filepath, ‘.php’ );
// タイムスタンプ部分を除去してCamelCaseに変換
$parts = explode( ‘_’, $filename, 2 );
return ‘Enterprise\Database\Migrations\\’ . str_replace( ‘ ‘, ”, ucwords( str_replace( ‘_’, ‘ ‘, $parts[1] ) ) );
}
}
// 初期化
new MigrationManager();
—
実際のマイグレーションファイルの書き方（例）
上記のシステムにおいて、実際に開発者が書くマイグレーションファイルの具象例だ。`migrations/` ディレクトリの中に `YYYYMMDDHHMMSS_add_index_to_postmeta.php` のような命名規則で配置する。
/
class AddIndexToPostmeta {
public function up() {
global $wpdb;
// wp_postmeta はデフォルトで (post_id, meta_key) のインデックスを持つが、
// 特定の巨大なカスタムメタ構造を高速化するためのカスタムテーブル作成例
$table_name = $wpdb->prefix . ‘custom_analytics_store’;
$charset_collate = $wpdb->get_charset_collate();
$sql = “CREATE TABLE {$table_name} (
id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
post_id BIGINT(20) UNSIGNED NOT NULL,
metric_key VARCHAR(64) NOT NULL,
metric_value LONGTEXT NOT NULL,
created_at DATETIME NOT NULL,
PRIMARY KEY (id),
KEY post_metric_idx (post_id, metric_key(32)),
KEY created_idx (created_at)
) {$charset_collate};”;
require_once( ABSPATH . ‘wp-admin/includes/upgrade.php’ );
dbDelta( $sql );
}
}
—
テクニカルリードからのアーキテクチャ上の重要アドバイス
1. MySQLの暗黙のコミット（Implicit Commit）に注意せよ
`ALTER TABLE` や `CREATE TABLE` などのDDL文は、実行時にトランザクションが強制的にコミットされる。そのため、PHP側の `try-catch` でロールバック構文（`ROLLBACK`）を書いても、DDLより前に実行されたSQLのロールバックは効かないケースがある。マイグレーションスクリプトは「1ファイル1責任（単一の安全な変更）」を徹底し、失敗した場合は手動リカバリが容易な設計にすること。
2. `dbDelta()` の厳格な構文規則を守れ
WordPress標準の `dbDelta()` は非常に気難しい。
- カラム定義の各行は必ず改行すること。
- `PRIMARY KEY` の定義は独立させること。
- 括弧のスペースやデータ型の記述が大文字か小文字かまで厳密にチェックされるため、公式ドキュメントの構文ルールを遵守すること。
3. 本番環境（大規模サイト）におけるデプロイ戦略
アクセス数が多いサイトの `admin_init` フックでマイグレーションを走らせるのは、レースコンディションや高負荷の原因になるため御法度だ。本稿では解説のため `admin_init` に置いたが、実務のプロダクション環境では WP-CLI コマンド（`wp eval` や独自のCLIパッケージ）としてラップし、CI/CDパイプライン（GitHub Actions等）やデプロイ時のメンテナンススクリプトとして静的実行するのが唯一の正解である。
データベースはサービスの生命線である。場当たり的な `CREATE TABLE IF NOT EXISTS` とは今日で決別し、洗練されたマイグレーション管理でスケーラブルなWordPressアプリケーションを構築してほしい。