Context & Why: The Production Table Alteration Dilemma
数千万行ものレコードを抱える稼働中のテーブルに対して ALTER TABLE を実行すると、本番データベースがいとも簡単にダウンしてしまうことがあります。近年のMySQLに搭載されているInnoDB Online DDLを使用した場合でも、大規模なスキーマ変更ではメタデータロック(MDL)が発生します。このロックによってクライアントのコネクションプールが枯渇し、レプリカの遅延が深刻化する原因となります。
The Problem: Unplanned Downtime and Replication Backlog
よくあるインシデントの例を考えてみましょう。あるエンジニアリングチームが、1億5,000万行の orders テーブルにインデックスとJSONカラムを追加する必要が生じました。開発者が通常のDDLコマンドを実行したところ、わずか45秒でアプリケーションのコネクションプールが上限の500接続に達してしまいました。普段なら2ミリ秒で返るクエリが排他的メタデータロックの背後に滞留し、同時にリードレプリカではスキーマ更新が単一のアプライアスレッドで実行されるため、レプリケーション遅延が600秒を超えてしまったのです。
The Root Cause: Triggers and Lock Contention
これまでデータベース管理者は、pt-online-schema-change のようなトリガーベースのツールに頼ってきました。低負荷時には信頼性が高いものの、トリガーはクライアントのトランザクション内で同期的に実行されます。INSERT、UPDATE、DELETE が発生するたびに、MySQLはシャドウテーブルへのトリガー書き込みを追加で実行せざるを得ません。秒間3,000件以上の書き込みが発生する環境では、このオーバーヘッドによってロック競合やトランザクションのデッドロック、深刻なレイテンシのスパイクが引き起こされます。
GitHubは、こうしたアーキテクチャ上の限界を克服するために gh-ost(GitHub’s Online Schema Transmogrifier)を開発しました。トリガーを利用するユーティリティとは異なり、gh-ostはトランザクションの書き込みパスを一切変更しません。代わりに、外部レプリカのようにMySQLのバイナリログ(binlog)から非同期に変更内容を読み取ります。設定可能なバッチ単位で既存レコードをコピーしつつ、本番トラフィックに同期的なロック負荷をかけることなくリアルタイムのイベントを再生します。
本番環境でスキーマ変更を実行する前には、必ず代表的なサンプルデータセットを用いてマイグレーションをテストしてください。ローカルのテストデータを変換したり、CSVダンプをJSONシードデータに変換したりする際には、ブラウザ上でローカルに動作し機密データが外部に送信されない toolcraft.appのCSV to JSONコンバーター が役立ちます。
Installation: Setting Up gh-ost and Database Privileges
gh-ostは外部依存関係のない単一のGoバイナリとして提供されているため、任意のデプロイホストや踏み台サーバーへのインストールが容易に行えます。
Step 1: Download and Install the Binary
GitHub Releasesからアーカイブを取得し、システムの実行パスにバイナリを配置します。
# Linux版リリースのダウンロード
GH_OST_VERSION="v1.1.6"
curl -LO "https://github.com/github/gh-ost/releases/download/${GH_OST_VERSION}/gh-ost-binary-linux-amd64-${GH_OST_VERSION}.tar.gz"
# バイナリの展開とインストール
tar -xzf "gh-ost-binary-linux-amd64-${GH_OST_VERSION}.tar.gz"
sudo mv gh-ost /usr/local/bin/
sudo chmod +x /usr/local/bin/gh-ost
# インストールの確認
gh-ost --version
Step 2: MySQL Prerequisites and Binary Log Settings
gh-ostはレプリケーションストリームから変更を読み取るため、行ベースレプリケーション(Row-based replication)が必須となります。my.cnf またはAWS RDSのパラメータグループで以下のオプションが有効になっていることを確認してください。
[mysqld]
server-id = 101
log-bin = mysql-bin
binlog_format = ROW
binlog_row_image = FULL
Step 3: Provisioning Database Privileges
gh-ost専用のサービスユーザーを作成します。従来のマイグレーションツールとは異なり、gh-ostには TRIGGER 権限が不要である点に注目してください。
CREATE USER 'ghost_ops'@'%' IDENTIFIED BY 'StrongGeneratedPassword123!';
-- バイナリログイベントのストリーミングとレプリケーション状態の監視
GRANT REPLICATION CLIENT, REPLICATION SLAVE ON *.* TO 'ghost_ops'@'%';
-- 対象スキーマでのシャドウテーブルの作成およびデータコピーの管理
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, LOCK TABLES
ON production_db.* TO 'ghost_ops'@'%';
-- MySQL 8.0以上でセッション変数を上書きするために必要
GRANT SYSTEM_VARIABLES_ADMIN ON *.* TO 'ghost_ops'@'%';
FLUSH PRIVILEGES;
Configuration: Production Flags and Throttling Strategy
安全なマイグレーションを実現するには、スキーマ変更ロジック、バックフィルの処理速度、そして動的なレプリカ遅延の上限値という3つの要素のバランスを取る必要があります。
Dry Run and Inspection
まずは必ず実行計画を検証してください。--execute を付けずにgh-ostを実行することで、主キーの検証、サポートされていない制約の検出、シャドウテーブル作成のシミュレーションを安全に行うことができます。
gh-ost \
--host=db-primary.internal.local \
--user=ghost_ops \
--password='StrongGeneratedPassword123!' \
--database="production_db" \
--table="orders" \
--alter="ADD COLUMN tracking_code VARCHAR(64) NULL, ADD INDEX idx_orders_tracking (tracking_code)" \
--verbose
gh-ostは主キーの構造をチェックし、外部キー制約が存在する場合は警告を発します。また、総実行時間を推定した上で、稼働中のデータに変更を加えることなく安全に終了します。
Executing with Replication-Aware Throttling
マルチレプリカ構成のクラスタに対して実行する場合、データベースの負荷に応じてマイグレーション処理を自動的に抑制(バックオフ)させる必要があります。以下のコマンドは、データベースの並行処理数を監視しながら、レプリカの遅延を1.2秒以内に制限します。
gh-ost \
--host=db-primary.internal.local \
--user=ghost_ops \
--password='StrongGeneratedPassword123!' \
--database="production_db" \
--table="orders" \
--alter="ADD COLUMN tracking_code VARCHAR(64) NULL, ADD INDEX idx_orders_tracking (tracking_code)" \
--chunk-size=1500 \
--max-lag-millis=1200 \
--throttle-control-replicas="db-replica-01.internal.local,db-replica-02.internal.local" \
--throttle-query="SELECT VARIABLE_VALUE FROM performance_schema.global_status WHERE VARIABLE_NAME='Threads_running' AND CAST(VARIABLE_VALUE AS UNSIGNED) > 40" \
--serve-socket-file="/tmp/gh-ost.orders.sock" \
--panic-flag-file="/tmp/ghost.panic.flag" \
--initially-drop-ghost-table \
--cut-over=atomic \
--execute
Understanding Key Configuration Options
--chunk-size=1500:データを1,500行単位のセグメントでコピーします。書き込み頻度の高いテーブルでは、行レベルロックの保持時間を最小限に抑えるため、500程度まで下げることを推奨します。--max-lag-millis=1200:いずれかの対象レプリカでレプリケーション遅延が1,200ミリ秒を超えた場合、チャンクのコピー処理を一時停止します。--throttle-query:このクエリがいずれかの結果行を返した場合にバックフィルを一時停止します。ここでは、アクティブなワーカースレッド数が40を超えた場合に一時停止するように設定しています。--serve-socket-file:Unixソケットで接続をリッスンし、運用担当者がマイグレーション設定をリアルタイムに確認または再調整できるようにします。--cut-over=atomic:ロックを伴う2テーブルのアトミックスワップ(RENAME TABLE orders TO _orders_del, _orders_gho TO orders)を使用し、切り替え中にトランザクションがドロップしないようにします。
Verification & Monitoring: Keeping Migrations Predictable
長時間のスキーマ変更を決して監視なしで実行してはなりません。運用担当者は、チャンクのコピー速度、スロットリングの状態、切り替え(カットオーバー)のタイミングを直接把握できる必要があります。
Dynamic Socket Control
コマンドで --serve-socket-file を指定しているため、nc(Netcat)などの標準的なUnixユーティリティを使用してマイグレーションの挙動を実行中に調整できます。
# マイグレーションの進捗状況と現在の完了予測時間(ETA)を確認
echo "status" | nc -U /tmp/gh-ost.orders.sock
# アプリケーションのトラフィックピーク時にチャンクサイズを縮小
echo "chunk-size=500" | nc -U /tmp/gh-ost.orders.sock
# 大量決済バッチの実行中にデータコピーフェーズを完全に一時停止
echo "throttle" | nc -U /tmp/gh-ost.orders.sock
# トラフィックの急増が収まった後にバックフィルを再開
echo "no-throttle" | nc -U /tmp/gh-ost.orders.sock
Monitoring Lag and Heartbeat Logs
マイグレーションフェーズ中、gh-ostは進捗状況のスナップショットを標準出力に直接出力します。
Copy: 42,150,000/152,000,000 27.7%; ETA: 3h12m; State: migrating; Current lag: 180ms; Replica lag: 210ms
Copy: 42,151,500/152,000,000 27.7%; ETA: 3h11m; State: throttled (replica db-replica-01 lag: 1350ms > 1200ms)
Copy: 42,151,500/152,000,000 27.7%; ETA: 3h14m; State: migrating; Current lag: 140ms; Replica lag: 320ms
db-replica-01 の遅延が1,350ミリ秒に跳ね上がると、gh-ostは自動的に行コピー処理を一時停止しました。遅延が1,200ミリ秒未満に戻ると、処理は何事もなかったかのようにスムーズに再開されました。
Verifying the Atomic Cut-Over
バックフィルが100%に達すると、gh-ostは残りのバイナリログイベントをフラッシュし、テーブルをアトミックに入れ替えてマイグレーションを完了します。
-- プライマリインスタンスで更新後のテーブル構造を確認
SHOW CREATE TABLE production_db.orders\G
-- インデックスの作成とカーディナリティを確認
SHOW INDEX FROM production_db.orders WHERE Column_name = 'tracking_code';
デフォルトでは、gh-ostは元のテーブルを _orders_del として保持します。これにより、アプリケーションで予期しないクエリの互換性問題が発生した場合でも、即座にフォールバックできます。24時間の運用サイクルでクエリパフォーマンスを検証した後、オフピーク時に残存テーブルを削除します。
DROP TABLE IF EXISTS production_db._orders_del;
バイナリログベースのマイグレーションにより、数十ギガバイト規模のテーブル変更を予測可能かつ安全に行うことができます。調整可能なチャンクサイズ、プロアクティブな遅延監視、そしてソケットによる動的制御を活用することで、アプリケーションのタイムアウトやレプリカの障害を招くリスクなく、スキーマ変更を本番環境へデプロイできます。

