---
name: migration-dry-run
description: Rehearse a database schema migration against a throwaway copy before the real window. Use when a migration touches a table that matters - adds columns, rewrites rows, drops or renames anything - and you need to know what breaks, what locks, and how long it takes before production finds out.
---

# Migration Dry Run

## When to use

- A migration rewrites, renames, or drops columns on a live table
- The change window is short and a surprise lock or full-table
  rewrite would blow it

Do NOT use for additive-only changes on small tables (new nullable
column, new table). Say the migration is low-risk and stop.

## Setup: the throwaway copy

1. Never rehearse against production. Restore a recent dump or
   snapshot into a scratch database with the same engine version.
2. Note the row counts of the tables the migration touches. If the
   copy is much smaller than production, say so - timing findings
   scale with table size and cannot be quoted as production numbers.
3. Record the engine and version. Lock behaviour differs across
   versions; a finding without a version is not a finding.

## The rehearsal

1. Apply the migration to the copy exactly as the deploy will run it -
   same tool, same order, same transaction settings.
2. Time each statement. Flag any statement that rewrites the table
   (type changes, defaults with backfill, index drops on large
   tables) separately from metadata-only changes.
3. Check what the application does DURING the migration: run the
   current code against the half-migrated schema if the deploy and
   migration are not atomic.
4. Roll back once, then VERIFY the rolled-back copy: row counts and
   spot-checked data match the pre-migration state. A down-migration
   that runs is not proof - dropped or renamed columns lose data
   silently. A migration that cannot be reversed in the window is a
   finding, not a footnote; name any step that loses data as
   irreversible, not merely "cannot undo".

## Output format

One line per statement: what it does, how long it took on the copy,
whether it locks or rewrites. Then three lists:

- **Will break**: code paths that fail against the new schema
- **Will wait**: statements that hold locks, with the rough hold time
- **Irreversible**: steps with no safe rollback inside the window,
  with data-loss steps called out by name

End with a go/no-go recommendation and the conditions attached.

## Hard boundaries

- Never run against production or a production replica with traffic.
- Never quote copy timings as production timings - report the size
  ratio next to every number.
- If the copy cannot be made representative, say the rehearsal is
  inconclusive instead of guessing.
