Review Migration

Use this skill when schema changes must be safe in real environments.

Quick Reference

HARD-GATE

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.

Core Process

1. Identify the database and table-size risk.
2. Separate schema changes from data backfills.
3. Check lock behavior for indexes, constraints, defaults, and rewrites.
4. Plan deployment order between app code and migration code.
5. Plan rollback or forward-fix strategy.

Extended Resources

Safe Patterns

• Add nullable column first, backfill later, enforce NOT NULL last.
• Add indexes concurrently when supported.
• Backfill in batches outside a long transaction when volume is high.
• Deploy code that tolerates both old and new schemas during transitions.
• Use multi-step rollouts for renames, type changes, and unique constraints.
• For every step, state the expected lock or table-rewrite risk explicitly; if negligible, say why. If the project uses strong_migrations, follow it. If it does not, apply the same safety rules manually.

Common Mistakes

Examples Risky (avoid):

add_column :orders, :status, :string, default: 'pending', null: false
Order.update_all("status = 'pending'")

Risk: Long lock; table rewrite if default is applied on large table.

Safe pattern:

# Step 1: add nullable column
add_column :orders, :status, :string

# Step 2 (separate deploy): backfill in batches outside migration

# Step 3 (after backfill): add constraint
change_column_null :orders, :status, false
change_column_default :orders, :status, from: nil, to: 'pending'

Type change rollout pattern:

1. Add the new typed column as nullable.
2. Dual-write old and new columns from application code.
3. Backfill in batches outside the migration transaction.
4. Read from the new column after parity checks pass.
5. Stop writing the old column, then drop it in a later deploy.

• PATTERNS.md

Output Style

1. List risks first.
2. For each risk include: Migration step, likely failure mode, explicit lock/table-rewrite risk, safer rollout, rollback or forward-fix note.
3. Ensure backwards compatibility steps are included.
4. Always include explicit phased patterns for column renames, type changes, and unique constraints. If one does not apply, mark it Not applicable and explain why.
5. Language — Must be in English unless explicitly requested otherwise.

Integration