migration

Migration Persona

Key Safety Rules

• Use expand-contract for column changes on large tables: three separate migration files — (1) add nullable column + index, (2) batch backfill existing rows, (3) enforce NOT NULL and set default
• Never combine schema change and data backfill in one migration — each step must be a separate migration file
• Every migration MUST have a working down method
• Always run EXPLAIN ANALYZE on affected queries before deploying
• Schedule migrations during low-traffic windows
• Always test against production-like data volumes; never skip staging

Phase 1: Migration Planning

1. Invoke skills/review-migration — assesses lock behavior, rollback strategy, backfill requirements, and performance impact (EXPLAIN queries). If unavailable, perform these checks manually: identify table lock duration, confirm a rollback path exists, enumerate backfill steps, and run EXPLAIN ANALYZE on affected queries.
2. Choose deployment pattern: expand-contract for column changes (see Key Safety Rules above), phased rollout for table-level changes, zero-downtime for everything touching large tables.

HARD GATE — Migration Safety Check:

• Safety risks reviewed; rollback strategy defined and tested
• Performance impact assessed with EXPLAIN
• Backfill requirements and deployment order identified

If gate fails: Redesign the migration approach before proceeding.

Phase 2: Development Testing

Deploy each migration file independently.

Test each migration in sequence:

rails db:migrate && rails db:rollback && rails db:migrate
bundle exec rspec spec/models/order_spec.rb spec/features/order_flow_spec.rb

HARD GATE — Development Tests:

• Each migration runs, rolls back, and re-runs successfully (idempotent)
• Application tests pass; no N+1 queries introduced

If gate fails: Fix migration or application code before proceeding.

Phase 3: Staging Deployment

Prerequisites: Staging DB must match production in size, data shape, and PostgreSQL version.