migration

name	migration
description	任意の ORM/データベーススタックに適用可能な安全なデータベーススキーママイグレーションパターン。以下の場合に使用: - データベーススキーマの変更（カラム・テーブルの追加/削除） - 安全なマイグレーションの実行 - データベースのバージョニングとロールバックの管理 - マイグレーションリスクの評価や安全なデプロイの計画 - スキーマドリフトやマイグレーションの競合への対処 Trigger phrases: database migration, schema change, add column, migration rollback, schema drift
allowed-tools	Bash, Read, AskUserQuestion, Write, Glob, Grep, WebSearch, WebFetch
model	sonnet
user-invocable	true

データベースマイグレーション

任意の ORM とデータベースに適用可能な安全なスキーママイグレーションパターン。このスキルはマイグレーションの原則と安全パターンを定義するものであり、特定の ORM コマンドを定義するものではない。

設計原則

1. プロジェクトのツールを発見: プロジェクトが使用する ORM/マイグレーションツールを検出
2. コマンドをリサーチ: WebSearch で現在の ORM コマンド構文を調査
3. 安全第一: ツールに関係なく安全なマイグレーションパターンに従う
4. 常にロールバック可能に: 変更の取り消しを計画

---

マイグレーション安全チェックリスト

マイグレーション実行前:

• バックアップが存在するか復元可能
• マイグレーションが可逆（ダウンマイグレーション定義済み）
• データ損失リスクを特定済み
• 非本番環境でテスト済み
• スキーマドリフトを確認済み

---

ツール発見

ステップ 1: マイグレーションツールの検出

特定のツールを前提とせずにマイグレーション関連の設定を探す:

# マイグレーションディレクトリと設定を確認
ls -la migrations/ db/migrate/ alembic/ prisma/ drizzle/ 2>/dev/null
ls -la *migrate* *migration* *.prisma diesel.toml 2>/dev/null

# 依存関係でマイグレーションツールを確認
grep -E 'prisma|drizzle|alembic|django|sequelize|typeorm|knex|goose|diesel|flyway' \
  package.json pyproject.toml requirements.txt go.mod Cargo.toml pom.xml 2>/dev/null

ステップ 2: プロジェクトコマンドを見つける

# マイグレーションスクリプトを確認
grep -E 'migrate|migration|db:' package.json 2>/dev/null
grep -E '^(migrate|db)' Makefile 2>/dev/null

ステップ 3: 現在のコマンドをリサーチ

ツールが検出されたがコマンドが不慣れな場合:

WebSearch: "[ORM/ツール名] migration commands [year]"
WebFetch: [公式ドキュメント] → "Extract migration CLI commands"

---

安全なマイグレーションパターン

これらのパターンは任意のデータベースとマイグレーションツールに適用:

カラムの追加

安全なアプローチ（NOT NULL の場合は 2 ステップ）:

ステップ 1: nullable としてカラムを追加
ステップ 2: 必要に応じてデータをバックフィル
ステップ 3: NOT NULL 制約を追加（必要な場合）

理由: NOT NULL カラムを直接追加すると既存の行で失敗する。

カラムの削除

安全なアプローチ（3 ステップ）:

ステップ 1: アプリケーションコードでカラムの使用を停止
ステップ 2: アプリケーション変更をデプロイ
ステップ 3: マイグレーションでカラムを削除

理由: コードが使用中のカラムを削除するとエラーが発生する。

カラムのリネーム

安全なアプローチ（4 ステップ）:

ステップ 1: 新しいカラムを追加（旧のコピー）
ステップ 2: 旧から新にデータをコピー
ステップ 3: 新しいカラムを使用するようにコードを更新
ステップ 4: 旧カラムを削除

理由: 直接リネームするとデプロイ中に実行中のコードが壊れる。

インデックスの追加

安全なアプローチ:

- 小さなテーブル: 直接インデックス作成
- 大きなテーブル: コンカレント/オンラインインデックス作成を使用

理由: インデックス作成はテーブルをロックする。コンカレント作成はダウンタイムを回避。

注: コンカレントインデックスの構文はデータベースによって異なる - 特定のデータベースについてリサーチすること。

---

リスク評価

変更タイプ	リスクレベル	軽減策
nullable カラム追加	低	不要
デフォルト値付きカラム追加	低	デフォルト値を確認
NOT NULL カラム追加	中	まず nullable で追加、バックフィル、制約追加
カラム削除	高	コードが使用していないことを確認
カラムリネーム	高	追加/コピー/削除パターンを使用
カラム型変更	高	データ互換性をテスト
インデックス追加（小テーブル）	低	不要
インデックス追加（大テーブル）	中	コンカレント作成を使用
インデックス削除	低	クエリに不要であることを確認

---

ロールバック戦略

常にロールバックを計画する:

1. 可逆マイグレーション: アップとダウンの両方のマイグレーションを定義
2. ロールバックをテスト: デプロイ前にダウンマイグレーションが動作することを確認
3. ロールバックスクリプトを保管: 必要に応じて手動ロールバック SQL を保存
4. ロールバック手順を文書化: デプロイチェックリストに含める

ロールバックコマンド

マイグレーションツールのロールバックコマンドを発見する:

WebSearch: "[マイグレーションツール] rollback command"

---

本番チェックリスト

本番環境にマイグレーションをデプロイする前:

1. ローカルでマイグレーションをテスト済み
2. ステージング/プレビューでマイグレーションをテスト済み
3. データベースバックアップを作成/確認済み
4. ロールバック計画を文書化・テスト済み
5. ダウンタイムウィンドウをスケジュール済み（必要な場合）
6. チームにマイグレーションを通知済み
7. 問題に対するモニタリング準備完了
8. アプリケーションコードが旧スキーマと新スキーマの両方に互換性あり

---

よくある問題

スキーマドリフト

データベースがマイグレーションと異なる場合:

1. 現在のスキーマと期待されるスキーマを比較
2. 乖離した変更を特定
3. いずれかを実施:
   • 現在の状態に合わせるマイグレーションを生成
   • マイグレーション状態にリセット（開発環境のみ）

マイグレーションの競合

複数のマイグレーションが競合する場合:

1. 最新のマイグレーションを pull
2. 順序の問題を確認
3. マイグレーションファイルの競合を解決
4. マイグレーションを再実行

失敗したマイグレーション

マイグレーションが途中で失敗した場合:

1. 何が適用されたかを確認
2. 部分的な変更を手動で修正またはロールバック
3. マイグレーションを修正して再試行
4. マイグレーションを解決済みとしてマーク（ツール固有）

---

Rules (L1 - Hard)

データの安全性に不可欠。違反はデータ損失を引き起こす可能性。

• ALWAYS: マイグレーション前にバックアップ（リカバリ要件）
• NEVER: 明示的な確認なしに破壊的マイグレーションを実行しない
• NEVER: 本番環境で reset/drop コマンドを実行しない
• NEVER: マイグレーションが自動的に可逆であると仮定しない

Defaults (L2 - Soft)

安全な操作に重要。適切な理由がある場合はオーバーライド可。

• まず非本番環境でマイグレーションをテスト
• ロールバック計画を文書化
• コマンド実行前にプロジェクトのマイグレーションツールを発見
• WebSearch で現在のコマンド構文を確認
• ORM 固有のコマンドをハードコードしない（発見する）

Guidelines (L3)

堅牢なマイグレーション実践のための推奨事項。

• consider: カラムリネームには追加/コピー/削除パターンの使用を検討
• prefer: 大きなテーブルにはコンカレントインデックス作成を推奨
• consider: マイグレーション前のスキーマドリフトチェックを検討