review-migration

マイグレーションのレビュー

実際の環境でスキーマ変更が安全でなければならない場合に、このスキルを使用します。

ハードゲート

DO NOT combine schema change and data backfill in one migration.
DO NOT add NOT NULL on a column that hasn't been fully backfilled.
DO NOT drop columns before all code references are removed.

中心となるプロセス

1. データベースとテーブルサイズのリスクを特定します。
2. スキーマ変更とデータのバックフィルを分離します。
3. インデックス、制約、デフォルト値、および書き換えに関するロックの挙動を確認します。
4. アプリケーションコードとマイグレーションコードの間のデプロイ順序を計画します。
5. ロールバックまたは前方修正 (forward-fix) の戦略を計画します。

プロジェクトで strong_migrations を使用している場合は、それに従います。使用していない場合は、同じ安全ルールを手動で適用します。

安全なパターンとよくある間違い

操作	安全なパターン	よくある間違い	失敗する理由
カラムの追加	まず NULL 許容で追加し、後でバックフィルし、最後に NOT NULL を適用	大きなテーブルに対して add_column :t, :col, :string, null: false, default: "x"	テーブル書き換え + ロック (PG < 11)
インデックスの追加 (大きなテーブル)	algorithm: :concurrently (PG) / :inplace (MySQL) + disable_ddl_transaction!	algorithm: :concurrently を付けずに add_index :users, :email	共有ロックが書き込みをブロック
データのバックフィル	マイグレーションのトランザクション外でのバッチジョブ、レプリケーション遅延を減らすためのスロットリング	マイグレーション内での User.update_all(...)	トランザクションロックが全期間保持される
カラムの名前変更	新しいカラムを追加し、データをコピーし、呼び出し元を移行し、古いカラムを削除	カラムを直接名前変更	デプロイ中に実行中のアプリが壊れる
NOT NULL の追加	バックフィルで全ての行に値があることを確認した後	バックフィルの完了前に NOT NULL を適用	値が欠けている行で失敗またはロック
外部キーの追加	孤立したレコードをクリーンアップした後	孤立レコードをクリーンアップせずに FK を追加	マイグレーション時に制約違反
カラムの削除	まずコードの参照を削除し、デプロイしてからカラムを削除	コードがまだ読み取っている間にカラムを削除	実行時の unknown attribute エラー

各ステップについて、予想されるロックまたはテーブル書き換えのリスクを明示的に記述します。無視できる場合は、その理由を述べます。

移行期間中は、古いスキーマと新しいスキーマの両方に対応できるコードをデプロイします。

コード例

並行インデックス (Rails / PostgreSQL):

class AddIndexOnUsersEmail < ActiveRecord::Migration[7.1]
  disable_ddl_transaction!

  def change
    add_index :users, :email, algorithm: :concurrently
  end
end

disable_ddl_transaction! が必要です — 並行インデックス作成はトランザクション内では実行できません。

NULL 許容ファーストのカラムと遅延 NOT NULL (Rails):

# Step 1 — Deploy: add nullable column
class AddConfirmedAtToUsers < ActiveRecord::Migration[7.1]
  def change
    add_column :users, :confirmed_at, :datetime
  end
end

# Step 2 — Backfill outside migration (background job or script)
User.in_batches(of: 1_000) do |batch|
  batch.update_all(confirmed_at: Time.current)
  sleep(0.05) # throttle to reduce replication lag
end

# Step 3 — Deploy: enforce NOT NULL only after all rows are filled
class ChangeConfirmedAtNotNull < ActiveRecord::Migration[7.1]
  def change
    change_column_null :users, :confirmed_at, false
  end
end

型変更のロールアウト (5 ステップ):

1. 新しい型のカラムを NULL 許容で追加します。
2. アプリケーションコードから古いカラムと新しいカラムの両方に書き込みます (デュアルライト)。
3. マイグレーションのトランザクション外でバッチ単位でバックフィルします。
4. パリティチェックが通った後、新しいカラムから読み取ります。
5. 古いカラムへの書き込みを停止し、後のデプロイでそれを削除します。

出力スタイル

1. 最初にリスクを列挙します。
2. 各リスクには以下を含めます: マイグレーションのステップ、想定される失敗モード、明示的なロック/テーブル書き換えのリスク、より安全なロールアウト、ロールバックまたは前方修正の注記。
3. 後方互換性のステップが含まれていることを確認します。
4. カラムの名前変更、型変更、および一意制約については、常に明示的な段階的パターンを含めます。該当しないものがある場合は、Not applicable とマークし、その理由を説明します。
5. 言語 — 明示的に他に要求されない限り、英語でなければなりません。

連携

スキル	いつ連携するか
code-review	マイグレーションを含む PR をレビューするとき
implement-background-job	スキーマ変更後に実行されるバックフィルジョブの場合
security-check	マイグレーションが機密データを露出または移動する場合