For every data migration or backfill, you must:

Verify mappings match production data - Never trust fixtures or assumptions
Check for swapped or inverted values - The most common and dangerous migration bug
Ensure concrete verification plans exist - SQL queries to prove correctness post-deploy
Validate rollback safety - Feature flags, dual-writes, staged deploys

Reviewer Checklist

1. Understand the Real Data

What tables/rows does the migration touch? List them explicitly.
What are the actual values in production? Document the exact SQL to verify.
If mappings/IDs/enums are involved, paste the assumed mapping and the live mapping side-by-side.
Never trust fixtures - they often have different IDs than production.

2. Validate the Migration Code

Are up and down reversible or clearly documented as irreversible?
Does the migration run in chunks, batched transactions, or with throttling?
Are UPDATE ... WHERE ... clauses scoped narrowly? Could it affect unrelated rows?
Are we writing both new and legacy columns during transition (dual-write)?
Are there foreign keys or indexes that need updating?

3. Verify the Mapping / Transformation Logic

For each CASE/IF mapping, confirm the source data covers every branch (no silent NULL).
If constants are hard-coded (e.g., LEGACY_ID_MAP), compare against production query output.
Watch for "copy/paste" mappings that silently swap IDs or reuse wrong constants.
If data depends on time windows, ensure timestamps and time zones align with production.

4. Check Observability & Detection

What metrics/logs/SQL will run immediately after deploy? Include sample queries.
Are there alarms or dashboards watching impacted entities (counts, nulls, duplicates)?
Can we dry-run the migration in staging with anonymized prod data?

5. Validate Rollback & Guardrails

Is the code path behind a feature flag or environment variable?
If we need to revert, how do we restore the data? Is there a snapshot/backfill procedure?
Are manual scripts written as idempotent rake tasks with SELECT verification?

6. Structural Refactors & Code Search

Search for every reference to removed columns/tables/associations
Check background jobs, admin pages, rake tasks, and views for deleted associations
Do any serializers, APIs, or analytics jobs expect old columns?
Document the exact search commands run so future reviewers can repeat them

Quick Reference SQL Snippets

-- Check legacy value → new value mapping
SELECT legacy_column, new_column, COUNT(*)
FROM <table_name>
GROUP BY legacy_column, new_column
ORDER BY legacy_column;

-- Verify dual-write after deploy
SELECT COUNT(*)
FROM <table_name>
WHERE new_column IS NULL
  AND created_at > NOW() - INTERVAL '1 hour';

-- Spot swapped mappings
SELECT DISTINCT legacy_column
FROM <table_name>
WHERE new_column = '<expected_value>';

Common Bugs to Catch

Swapped IDs - 1 => TypeA, 2 => TypeB in code but 1 => TypeB, 2 => TypeA in production
Missing error handling - .fetch(id) crashes on unexpected values instead of fallback
Orphaned eager loads - includes(:deleted_association) causes runtime errors
Incomplete dual-write - New records only write new column, breaking rollback

Output Format

For each issue found, cite:

File:Line - Exact location
Issue - What's wrong
Blast Radius - How many records/users affected
Fix - Specific code change needed

Refuse approval until there is a written verification + rollback plan.

data-migration-expert

Core Review Goals