migration-risk-analyzer

移行リスク分析

データベース移行の体系的なリスク評価：DDL／DML 操作の解析、ロックの種類と継続時間の分類、ダウンタイムの見積もり、ロールバック戦略の策定、不可逆な変更の特定、デプロイに関する推奨事項と移行前後の検証クエリの作成を行います。

参考ファイル

ファイル	内容	読み込むタイミング
references/lock-matrix.md	PostgreSQL、MySQL の操作とロックの種類の対応表	常に
references/safe-patterns.md	オンライン DDL パターン、ダウンタイムなしの移行手法	リスク軽減が必要な場合
references/rollback-templates.md	一般的な DDL 操作のロールバックスクリプト	ロールバック戦略を求められた場合
references/validation-queries.md	移行前後の検証用 SQL テンプレート	常に

前提条件

• 移行用 SQL または移行ファイル（Alembic、Django、Flyway など）
• 対象のデータベースエンジン（PostgreSQL、MySQL）
• 影響を受けるテーブルのおおよそのサイズ（処理時間の見積もり用）

ワークフロー

フェーズ 1：移行の解析

移行スクリプトからすべての操作を抽出します。

1. DDL 操作 — CREATE TABLE、ALTER TABLE（ADD／DROP／MODIFY COLUMN、ADD／DROP INDEX）、DROP TABLE、RENAME TABLE
2. DML 操作 — 既存データに対する UPDATE、INSERT、DELETE
3. インデックス操作 — CREATE INDEX、DROP INDEX、REINDEX
4. 制約操作 — ADD／DROP FOREIGN KEY、ADD／DROP CHECK、ADD／DROP NOT NULL

フェーズ 2：ロックのリスク評価

各操作について、ロックの種類と影響を特定します。

ロックレベル	影響	例
ロックなし	影響なし	CREATE TABLE、CREATE INDEX CONCURRENTLY（PG）
共有ロック	書き込みをブロックし、読み取りは許可	CREATE INDEX（並行処理なし）
排他ロック	すべてのアクセスをブロック	ALTER TABLE ADD COLUMN（MySQL < 8.0）、DROP TABLE
行レベルロック	対象の行のみをブロック	WHERE 句を指定した UPDATE

次の点を考慮します。

• テーブルサイズ（10 行のテーブルに対するロックは無視できる程度ですが、1 億行のテーブルでは重大です）
• 同時実行されるクエリのパターン（書き込み頻度の高い OLTP と、バッチクエリを使う OLAP の違い）
• ロックタイムアウトの設定

フェーズ 3：処理時間の見積もり

操作の種類とテーブルサイズに基づいて見積もります。

操作	小規模テーブル（<100K）	中規模（100K-10M）	大規模（>10M）
ADD COLUMN（NULL 許容）	< 1s	< 1s	< 1s（PG）／数分（MySQL）
ADD COLUMN（デフォルト値あり）	< 1s	数秒	数分（テーブルの書き換え）
CREATE INDEX	< 1s	数秒	数分～数時間
ADD NOT NULL	数秒	数分	数時間（全件スキャン）
バックフィル UPDATE	数秒	数分	数時間

フェーズ 4：ロールバックの設計

各操作について、元に戻せるかどうかを判断します。

操作	元に戻せるか	ロールバック
ADD COLUMN	はい	DROP COLUMN
DROP COLUMN	いいえ	データが失われます
ADD INDEX	はい	DROP INDEX
DROP TABLE	いいえ	データが失われます
RENAME COLUMN	はい	元の名前に戻す
ALTER TYPE	場合による	精度が失われる可能性があります
UPDATE data	場合による	古い値が保持されている場合に限ります

元に戻せない操作については、バックアップ戦略を推奨します。

フェーズ 5：レポートの作成

デプロイに関する推奨事項を含むリスク評価を作成します。

出力形式

## Migration Risk Analysis

### Summary
- **Operations:** {N} DDL, {M} DML
- **Tables affected:** {list with row counts}
- **Overall risk:** {High | Medium | Low}
- **Estimated duration:** {range}
- **Requires downtime:** {Yes | No}

### Operation Risk Table

| # | Operation | Risk | Lock Type | Est. Duration | Reversible |
|---|-----------|------|-----------|---------------|------------|
| 1 | {SQL operation} | {High/Med/Low} | {lock type} | {time} | {Yes/No} |

### Lock Analysis
- **Exclusive locks:** {list of operations that block all access}
- **Maximum lock duration:** {estimated time}
- **Affected queries:** {types of queries that will be blocked}

### Rollback Strategy

#### Reversible Operations
```sql
-- Rollback for operation 1: {description}
{rollback SQL}

元に戻せない操作

• {operation} — 元に戻せません。軽減策：

  -- Backup before migration
  {backup SQL}
  

マイグレーション前のチェックリスト

• データベースのバックアップが完了している
• ロールバックスクリプトをステージング環境でテスト済み
• （必要な場合）トラフィックの削減を確認済み
• 監視とアラートを設定済み
• 関係者に通知済み
• ロック待ちに備えてコネクションプールのサイズを調整済み

マイグレーション後の検証

-- Verify structural changes
{validation queries}

-- Verify data integrity
{integrity checks}

デプロイの推奨事項

戦略： {Online | Low-Traffic Window | Maintenance Window} 推定ダウンタイム： {time or "None with proper execution"} ロールバック時間： {time} リスク軽減策： {specific recommendations}

## Calibration Rules

1. **Assume large tables.** If table size is unknown, assume it's large enough for
   locks to matter. Overestimating risk is safer than underestimating.
2. **Engine-specific analysis.** PostgreSQL and MySQL handle DDL very differently.
   PostgreSQL can add nullable columns without table rewrite; MySQL often cannot.
   Always target the specific engine.
3. **Irreversible means irreversible.** DROP COLUMN destroys data. No amount of
   rollback scripting recovers it. Flag every irreversible operation prominently.
4. **Test the rollback.** Rollback scripts must be tested in staging before the
   migration runs in production. Untested rollback is no rollback.
5. **Sequence matters.** The order of operations affects lock duration. Adding a
   column then backfilling then adding NOT NULL is safer than adding a NOT NULL
   column with a default.

## Error Handling

| Problem | Resolution |
|---------|------------|
| Database engine not specified | Ask. Lock behavior differs significantly between engines. |
| Table sizes unknown | Analyze without duration estimates. Flag that estimates require row counts. |
| ORM migration format (not raw SQL) | Parse the ORM migration file. Translate operations to SQL equivalents for analysis. |
| Migration has data-dependent logic | Flag conditional operations. Risk depends on data state at migration time. |
| Multiple migrations in sequence | Analyze each independently and as a group. Cross-migration lock accumulation is a risk. |

## When NOT to Analyze

Push back if:
- The migration is for a development/staging database — risk analysis is for production
- The migration only creates new tables (no ALTER, no existing data) — low risk by definition
- The user wants migration execution, not analysis — this skill assesses risk, it doesn't run migrations

## Rationalizations

| Rationalization | Reality |
|---|---|
| "It's backwards compatible" | Backwards compatible at the schema level doesn't mean backwards compatible at the application level — query plans, ORM mappings, and application code all interact |
| "We can roll back" | Rollback is not free — data written after migration may not survive rollback; DROP COLUMN has no rollback without backup |
| "It's a small table" | Table size is one factor — lock duration, concurrent write rate, and replication lag matter more than row count |
| "We've run this migration type before" | Past success doesn't predict future success — different data distribution, different load, different constraints |
| "Downtime window is long enough" | Estimate based on dev data, not production — migration on 10k rows takes seconds; on 50M rows with indexes, it takes hours |
| "The ORM handles it" | ORMs generate SQL, they don't guarantee safety — `ALTER TABLE` locking behavior is engine-specific and ORM-opaque |

## Red Flags

- No estimate of migration duration based on production data volume
- No rollback plan or rollback plan that doesn't account for data written post-migration
- Analyzing migration SQL without checking the current table size and write rate
- No consideration of replication lag in multi-replica setups
- Assuming zero downtime without verifying lock behavior for the specific DDL operation
- Skipping index analysis — adding an index on a large table can lock writes for minutes to hours

## Verification

- [ ] Production table sizes and row counts documented for all affected tables
- [ ] Lock behavior identified for each DDL statement (exclusive lock, no lock, etc.)
- [ ] Migration duration estimated using production-scale data, not dev fixtures
- [ ] Rollback plan documented with specific steps and data preservation guarantees
- [ ] Concurrent write impact assessed — what happens to in-flight transactions during migration
- [ ] Replication lag impact assessed for multi-replica configurations