How to prove a data migration is correct before you flip the switch

Most migrations that fail don’t fail because the code was wrong — they fail because nobody proved the data was right before cutover, and the gap between “looks right” and “is right” only becomes visible once customers hit it.

Spot checks aren’t proof

Manually sampling a handful of records and confirming they match is useful as a sanity check, but it’s not verification — it tells you the migration probably works for the cases you happened to look at, which are usually the easy, common ones. The failures that matter are in the edge cases: the record with a null field the new schema doesn’t expect, the row with a timestamp from before a timezone policy changed, the account with a state the old system allowed and the new one doesn’t.

What actual verification looks like

Real verification means comparing the full dataset, not a sample: every record in the old system has a corresponding record in the new one, every field maps to an equivalent value, and every computed or derived value (totals, statuses, aggregates) produces the same result in both systems. This is usually built as an automated diff process that runs continuously during the migration window, not a one-time check right before cutover.

Defining “equivalent” carefully

Not every field needs to match byte-for-byte — a timestamp stored in a different format, or a status enum renamed during the migration, can still be correct without being identical. The verification process needs an explicit definition of equivalence for each field, agreed on before the diff runs, so a real discrepancy doesn’t get waved away as a formatting difference, and a formatting difference doesn’t get treated as a blocking bug.

The bar for flipping the switch

Cutover should happen when the diff has been clean across a full production data cycle, not when it’s been clean once. A single clean run can be luck; a sustained clean run across real traffic and real edge cases is evidence you can actually cut over on. This verification work is core to the cutover execution phase of a migration engagement.