drizzle-safe-migrations

Drizzle の安全なマイグレーション

概要

このスキルを使用して、監査可能で、デプロイに安全な、Drizzle のマイグレーションモデルに沿った方法でデータベースのマイグレーションを実行します。

基本ルール

• スキーママイグレーションは、既存のプロジェクトスクリプトとパッケージマネージャーを使って生成します。以下の bun run db:generate は一例であり、必須のスクリプト名ではありません。
• 生成されたスキーママイグレーションファイルは、手作業で編集しないでください。
• データのバックフィルはカスタムマイグレーション（bun run db:generate -- --custom --name <name>）として生成し、そのカスタム SQL ファイルのみを編集してください。
• 制約を厳しくする前に、データの正規化を行ってください。
• 一度限りのデータ修正は、緊急のホットフィックスで一時的な緩和策が必要な場合を除き、隠れたランタイムロジックではなく、マイグレーション履歴に残してください。

ワークフロー

1. 変更を分類します：
   • schema-only：列、テーブル、インデックス、デフォルト値のみの変更。
   • data+schema：新しい制約やデフォルト値を適用する前に、既存の行を変換する必要があります。
2. data+schema の場合、最初にカスタムマイグレーションを作成します：
   • bun run db:generate -- --custom --name <descriptive_name>
   • 冪等なバックフィル SQL を追加します。
3. 2 番目にスキーママイグレーションを生成します：
   • bun run db:generate
4. drizzle/meta/_journal.json でマイグレーションの順序を確認します：
   • バックフィルマイグレーションのインデックスは、制約を厳しくするマイグレーションのインデックスより小さくする必要があります。
5. 生成された SQL とスナップショットを確認します：
   • バックフィルマイグレーションには、意図したデータ変更のみが含まれていること。
   • スキーママイグレーションには、制約、デフォルト値、型の変更が含まれていること。
6. 既存データがある場合と新規インストールの場合の両方を対象に、担当するマイグレーションスイートを実行し、必要なプロジェクトゲートも通します。既存の検証結果を再利用してください。無関係なバックエンドスイートは、このスキルの追加ゲートではありません。
7. 該当する場合は、重要なロールアウトリスクと復旧手順を記録します：
   • 想定されるデータ変換。
   • ロックのリスクがある領域。
   • ロールバック戦略。

バックフィルの要件

• 制限的な WHERE 句を使用します。
• 冪等な更新を優先します（UPDATE ... WHERE status = 'legacy_value'）。
• 無関係な DDL と DML を同じマイグレーションに混在させないでください。
• SQL は明示的かつ最小限にします。

制約を厳しくする手順

許可される値（enum/check）を削除する場合：

1. 既存の行を有効な対象値にバックフィルします。
2. デフォルト値を新しい値に更新します。
3. check/enum 制約を厳しくします。

大規模なテーブルや高い稼働率目標がある場合は、実際のデータベースとドライバーがサポートする、段階的な制約検証を評価してください。PostgreSQL の NOT VALID / VALIDATE CONSTRAINT が適用されるのは、サポート対象の制約種別に限られます。

アンチパターン

• 生成されたスキーママイグレーションファイルを手作業で編集する。
• 既存データをバックフィルする前に制約を厳しくする。
• マイグレーションの成果物を残さず、アプリケーションの起動コードに一度限りのマイグレーションロジックを隠す。
• Drizzle のジャーナルで順序を検証せずにマイグレーションを実行する。

参考資料

• コマンドのテンプレートとレビュー用チェックリストについては、references/production-playbook.md を参照してください。