DB マイグレーションヘルパー

コース構成

このコースで学ぶこと

1. 01

   DB マイグレーションの怖さ

   マイグレーション失敗は本番事故の典型。Claude Code で『書く前にチェック』『書いたあと検証』を体系化。

   DB スキーマ変更は、コード変更と違って『戻すのが難しい』。NOT NULL 追加、列削除、インデックス追加（ロック）など、本番で走らせた瞬間に取り返しがつかないことがあります。

   Claude Code に既存スキーマ + 変更要件を渡して、(1) マイグレーション SQL の自動生成、(2) ロックリスクの評価、(3) ロールバック手順、(4) ステージング検証チェックリスト、まで一気通貫で生成すれば、事故の確率を大きく下げられます。

   既存スキーマと変更要件を渡す
2. 02

   既存スキーマと変更要件を渡す

   現状のスキーマ（DDL or 自動生成）+ 変更要件（自然言語）から始める。

   text

   # 変更要件の例（要件.md）
   ## やりたいこと
   users テーブルに `last_login_at`（NULLABLE TIMESTAMP）を追加。
   さらに `email` に部分インデックス（is_active = true のもののみ）を追加。
   
   ## 制約
   - 本番テーブル: 5000 万行
   - 適用時間: 5 分以内
   - ダウンタイム不可
   - ロールバック手順必須

   DB マイグレーションの怖さマイグレーション生成と検証プロンプト
3. 03

   マイグレーション生成と検証プロンプト

   要件を Claude に渡すと、マイグレーション SQL + リスク評価 + ロールバック手順を出す。

   text

   > migrations/requirements/2026-05-add-last-login.md を基に、Drizzle マイグレーションを生成。
   
   ## 必ず含める
   1. **up.sql** — 適用 SQL
      - 大規模テーブルなら `CREATE INDEX CONCURRENTLY`
      - NOT NULL 追加なら default value or 2 段階で
   2. **down.sql** — ロールバック
   3. **ロック分析**
      - どの操作がテーブルロックを取るか
      - 想定実行時間（5000 万行で）
   4. **ステージング検証チェックリスト**
      - ロック確認方法（pg_locks）
      - パフォーマンス影響測定
      - ロールバック試験
   5. **本番適用 SOP**
      - 適用時刻（深夜 / メンテ枠）
      - 監視すべきメトリクス
      - エスカレーション基準

   出力イメージ生成されたマイグレーション計画（抜粋）

   ### up.sql
   ```sql
   ALTER TABLE users ADD COLUMN last_login_at TIMESTAMP;
   CREATE INDEX CONCURRENTLY idx_users_email_active
     ON users (email) WHERE is_active = true;
   ```
   
   ### ロック分析
   - ADD COLUMN（NULLABLE）: メタデータのみ、ロックは一瞬
   - CREATE INDEX CONCURRENTLY: テーブルロックなし。5000 万行で約 3〜4 分の想定
   …（down.sql / 検証チェックリスト / 本番 SOP）

   既存スキーマと変更要件を渡すロック・パフォーマンス影響の評価
4. 04

   ロック・パフォーマンス影響の評価

   Postgres / MySQL でやりがちなロック地雷を AI に指摘させる。

   • 🔴 `ALTER TABLE ADD COLUMN ... NOT NULL DEFAULT 'x'` — Postgres 11 未満ではテーブルリライト
   • 🔴 `CREATE INDEX` 通常版 — テーブル全体に AccessExclusiveLock
   • 🟢 `CREATE INDEX CONCURRENTLY` — オンライン、ただし失敗時の手動 cleanup 必要
   • 🟠 列削除 → CMS / アプリのキャッシュ無効化を忘れがち
   • 🟠 外部キー追加 → 既存データの整合チェックで時間がかかる
   マイグレーション生成と検証プロンプト本番適用前の必修チェックリスト
5. 05

   本番適用前の必修チェックリスト

   Claude が出したチェックリストに人間が必ず ✓ を入れる。

   手を動かす

   0 / 6

   • ステージングで同サイズのデータで試験済み
   • ロールバック SQL を実機で検証済み
   • メンテ枠 or 深夜帯に適用
   • 監視ダッシュボードを 2 名以上で見る
   • 適用後 1 時間の見守り体制
   • ロールバック判断基準の事前合意（〇〇分以内に△△しなければ rollback）

   Lv.4 — 権限とサンドボックス

   理解度チェック

   1. Q1.DB マイグレーションを AI 補助で運用するときに、AI 単独で完結させてはいけないのは？

      AUp/Down SQL の生成B本番適用判断と『ロールバック判断基準の事前合意』Cロックリスクの分析Dステージング検証スクリプトの生成

   2. Q2.DB マイグレーションヘルパーの目的として最も適切なのはどれか？

      A本番 DB へ AI が直接接続して変更するBスキーマ変更の Up/Down SQL 生成・ロックリスク分析・ロールバック計画立案を支援し、本番適用は人間が判断するCDB を停止するDDB のホスティング先を変える

   3. Q3.DB マイグレーションを Claude に手伝わせる際の安全設定として正しいのは？

      A本番 DB の接続文字列を直接 Claude プロセスに渡すB本番接続情報や `.env` は deny に入れ、staging のスキーマファイルだけを読ませるC全社員に DB の admin 権限を付けるDステージングを本番と同期する
   ロック・パフォーマンス影響の評価