マイグレーション事故事例とチェックリスト — 他人の失敗から学ぶ

+---------------------+--------------------------------------------------+
|  事故タイプ           |  何が起きるか                                     |
+---------------------+--------------------------------------------------+
|  ロック嵐            |  ALTERが強いロックを握り全クエリが待機             |
|  レプリ遅延          |  大量変更でレプリカが遅れ読み取り一貫性が崩れる       |
|  データ損失          |  誤った変換/削除で復旧不能なデータ消失              |
|  ロールバック不能     |  戻せない変更の後に問題発見                        |
|  タイムアウト         |  マイグレーションが長すぎてデプロイ/接続タイムアウト  |
|  重複実行            |  マイグレーションが同時に二度実行され状態が壊れる      |
+---------------------+--------------------------------------------------+

  ALTER TABLE (強いロック取得、5分かかる)
      |
  [クエリ1] 待機... [クエリ2] 待機... [クエリ3] 待機...
      |
  コネクションプール枯渇 -> 新規リクエスト拒否 -> 全面障害

[症状]
  02:14  デプロイ開始 (usersテーブルにcountryカラム追加)
  02:15  API応答時間が急増、タイムアウト殺到
  02:17  コネクションプール枯渇アラート
  02:31  マイグレーション強制中断、サービス復旧開始
  02:48  復旧完了 (合計34分の障害)

[原因]
  マイグレーション:
    ALTER TABLE users ADD COLUMN country VARCHAR(2) NOT NULL DEFAULT 'KR';
  usersテーブルは8千万行。旧DBではDEFAULTのあるNOT NULLカラム追加は
  全行を書き直し、その間ACCESS EXCLUSIVEロックを握る。
  ステージングは5万行なので0.1秒で終わり問題を検出できず。

[教訓]
  1. データ量を本番に近い環境でマイグレーションをリハーサルする。
  2. NOT NULL + DEFAULTはnullable追加 -> バックフィル -> 制約追加に分割する。
  3. マイグレーションリントで危険パターンをPRで捕まえる。

[症状]
  デプロイ翌日、カスタマーサポートに「配送先が消えた」という問い合わせ殺到。
  一部ユーザーのaddressフィールドが空値で表示される。

[原因]
  住所を単一文字列から構造化オブジェクトに変えるマイグレーション:
    - 新カラムaddress_jsonを追加
    - 旧address文字列をパースしてaddress_jsonを埋める
    - 旧addressカラムをDROP
  パースロジックが特定形式(カンマなしの住所)を処理できず約3%が空オブジェクトに。
  旧カラムを同じデプロイでDROPしたため原本が消え復旧不能。

[教訓]
  1. 変換と旧データ削除を同じデプロイに入れない(expand-contract)。
  2. 旧カラムは十分な検証期間の後に削除する。
  3. 変換前後でサンプル・不変条件検証を回す(空値比率チェック)。
  4. 破壊的作業の前に必ずバックアップ、PITR可能時点を確認する。

[症状]
  残高増減履歴テーブルに重複レコードを発見。
  一部ユーザーのポイントが二倍に付与された。

[原因]
  Kubernetesロールアウト中、initコンテナ方式でマイグレーションを実行。
  データバックフィルマイグレーション(過去取引にポイント再計算)が
  二つのPodでほぼ同時に開始。バックフィルSQLが冪等でなく
  (INSERTのみで重複チェックなし)同じデータを二度挿入。
  マイグレーションバージョンロックはDDLにはかかったが、バックフィルロジックの
  一部がロックの外で回るよう書かれていた。

[教訓]
  1. バックフィルを含むすべてのマイグレーションを冪等に書く
     (INSERT ... ON CONFLICT、または存在確認後に挿入)。
  2. マイグレーションは単一実行を保証する(Jobパターン、明示的ロック)。
  3. initコンテナ同時実行パターンを避ける。
  4. 金銭関連バックフィルはドライランで影響行数を先に確認する。

[症状]
  大量バックフィルのデプロイ後、一部ユーザーが「今変えた設定が見えない」と問い合わせ。
  読み取り専用APIが古いデータを返す。

[原因]
  3億行のテーブルに大量UPDATE(全ユーザーの等級再計算)を一度に実行。
  マスターでは8分で終わったが、読み取りレプリカ3台がこの変更を
  順次適用し最大22分遅れた。読み取りトラフィックはレプリカに
  分散していたため、その間ユーザーは古いデータを見た。

[教訓]
  1. 大量変更はバッチに分けてレプリカが追いつく時間を与える。
  2. バッチ間でレプリケーション遅延を監視し、閾値超過時は待機。
  3. 読み取り一貫性が重要な経路はマスターから読むかセッション一貫性を保証。
  4. バックフィル中はレプリ遅延アラートをオンにしておく。

-- バッチバックフィル (レプリ遅延を考慮し1万行ずつ、間に待機)
DO $$
DECLARE
  rows_affected int;
BEGIN
  LOOP
    UPDATE users SET tier = compute_tier(score)
    WHERE id IN (
      SELECT id FROM users WHERE tier IS NULL LIMIT 10000
    );
    GET DIAGNOSTICS rows_affected = ROW_COUNT;
    EXIT WHEN rows_affected = 0;
    PERFORM pg_sleep(0.5);  -- レプリカが追いつく時間
  END LOOP;
END $$;

[症状]
  CDパイプラインのマイグレーションステップが10分後タイムアウトで失敗。
  しかしマイグレーションはDBで実行中のまま。再試行が二つ目の
  マイグレーションを開始しロック競合が発生。

[原因]
  インデックス生成が見込みより長くかかりパイプラインタイムアウト(10分)を超過。
  パイプラインは失敗と判定したがDBセッションは生きてインデックス生成を継続。
  自動再試行が同じマイグレーションをまた開始 -> ロック衝突 -> 両方停止。

[教訓]
  1. マイグレーションのタイムアウトを実際の所要時間より十分長く取る。
  2. タイムアウト時はDBセッションを確実に整理(キャンセル)してから再試行する。
  3. 自動再試行を切るか、冪等性とロックで重複実行を防ぐ。
  4. 長くかかる作業(インデックス生成)はマイグレーションの外で非同期に。

+------------------+------------------+--------------------------------+
|  ツール           |  対象             |  方式                           |
+------------------+------------------+--------------------------------+
|  gh-ost          |  MySQL           |  binlogベース、トリガーなし      |
|  pt-online-schema|  MySQL           |  トリガーベースのシャドーテーブル  |
|  -change         |                  |                                |
|  pg_repack       |  PostgreSQL      |  bloat除去、テーブル再作成        |
+------------------+------------------+--------------------------------+

1. 元と同じ構造の新テーブルを作成 (望む変更を適用)
2. 元データを新テーブルへチャンク単位でコピー
3. コピー中に発生した変更を追跡し新テーブルに反映 (トリガーまたはbinlog)
4. 追いついたら短いロックでテーブル名を入れ替え (原子的スワップ)
5. 旧テーブルを整理

悪い:  ALTER TABLE ... (全テーブルを一度に書き直し、ロック5分)
良い:  nullable追加(速い) -> バッチバックフィル(1万行ずつ) -> 制約追加(速い)

expand   : 新構造を追加 (旧と共存、戻しやすい)
migrate  : 両方書き込み + バックフィル
switch   : 新構造へ読み取り切り替え
contract : 旧構造を削除 (十分安定した後、別デプロイ)

-- 変換後の空値比率を点検 (不変条件検証)
SELECT
  count(*) FILTER (WHERE address_json = '{}'::jsonb) AS empty_count,
  count(*) AS total,
  round(100.0 * count(*) FILTER (WHERE address_json = '{}'::jsonb) / count(*), 2) AS empty_pct
FROM users;
-- empty_pctが閾値を超えたらデプロイ中断

観測すべきシグナル:
  - マイグレーション経過時間 (見込み対比)
  - ロック待ちキューの長さ (pg_locks, SHOW PROCESSLIST)
  - レプリケーション遅延 (replica lag)
  - コネクションプール使用率
  - エラー率、応答時間

1. 本番スナップショットを隔離環境に復元 (データ量同一)
2. マイグレーションを実際に実行し所要時間を測定
3. ロック持続時間、レプリ遅延、ディスク使用量を観察
4. ロールバック/undo手順も一緒にリハーサル
5. 見込み所要時間とリスクをランブックに記録

+----------------------+----------------------------------------------+
|  メンテナンスウィンドウ |  無停止 (online)                              |
+----------------------+----------------------------------------------+
|  サービスを一時停止     |  サービス維持しつつ漸進的に適用                 |
|  単純、危険な作業も可能 |  複雑、expand-contract必須                    |
|  計画的ダウンタイム発生 |  ダウンタイムなし                             |
|  小規模/内部システム向き |  大規模/24x7サービス向き                      |
+----------------------+----------------------------------------------+

-- PostgreSQL: 現在のロック待ち状況を確認
SELECT
  blocked.pid AS blocked_pid,
  blocking.pid AS blocking_pid,
  blocked.query AS blocked_query,
  blocking.query AS blocking_query
FROM pg_stat_activity blocked
JOIN pg_stat_activity blocking
  ON blocking.pid = ANY(pg_blocking_pids(blocked.pid));

-- PostgreSQL: レプリケーション遅延を確認 (マスターで)
SELECT
  client_addr,
  state,
  pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn) AS lag_bytes
FROM pg_stat_replication;

-- 進行中の長いクエリを確認
SELECT pid, now() - query_start AS duration, query
FROM pg_stat_activity
WHERE state = 'active' AND now() - query_start > interval '1 minute'
ORDER BY duration DESC;

良いポストモーテムの構造:
  1. サマリー    - 何が、いつ、どれだけ影響したか (一段落)
  2. タイムライン - 分単位で何が起きたか
  3. 根本原因    - 「5 whys」で表面の先の原因まで
  4. 影響        - ユーザー/売上/データへの実際の影響
  5. 何がうまくいったか - 速い検知、良い対応なども記録
  6. アクションアイテム - 再発防止のための具体的・期限つき項目

事故: NOT NULLマイグレーションが本番を止めた
  なぜ? -> 8千万行を書き直しロックを握ったから
  なぜ? -> NOT NULL + DEFAULTが全体再書き込みを誘発するから
  なぜ? -> そのパターンが危険か知らず、レビューで捕まえられなかったから
  なぜ? -> マイグレーションリントがパイプラインになかったから
  なぜ? -> マイグレーションをコードのように検証する文化がなかったから
根本原因: ツール(リント)と文化(検証)の不在。個人の間違いではない。
アクション: リント導入 + 本番級リハーサル + 危険パターンのガイド文書化