A database migration can fail even when the script finishes without an error. A column may be truncated, a relationship may point to the wrong record, a default value may change business meaning, or an application may behave differently against the new schema. The first production cutover is a poor place to discover those assumptions.
A database migration dry run is a rehearsal using a representative copy of the source data and an environment that behaves like production. The goal is not simply to measure elapsed time. It is to prove what the migration changes, what it preserves, how the application behaves afterward, and how the team will recover if the result is not acceptable.
Start with a migration contract
Before copying a row, write down what “correct” means. A migration contract turns a risky technical task into a set of checks that people can review.
At minimum, define:
- Which source tables, files, or services are included.
- Which destination tables and fields receive each value.
- Which identifiers must remain stable.
- Which records are intentionally excluded, archived, merged, or transformed.
- Which application behaviors must still work after the move.
- What counts as a blocking failure.
- Who can approve the rehearsal and the final cutover.
For example, a customer platform may move from a legacy database to a normalized schema. The contract might say that every active customer keeps its source customer ID, every order still points to an existing customer, inactive records are retained but marked, and the application must be able to create a new order before the migration is approved.
Use representative data, not just a convenient sample
A tiny sample can prove that a script runs. It cannot prove that the migration handles the cases that make real systems difficult.
A useful rehearsal dataset includes ordinary records and edge cases: long names, empty optional fields, duplicate-looking values, Unicode characters, old records, recently changed records, nulls, dates near a boundary, large text fields, orphan candidates, and rows that have been historically rejected. Include enough related data to exercise foreign keys and business rules.
Protect the copy before it leaves the source boundary. Remove or mask sensitive values when the test does not require them. Keep the dataset inventory, masking rules, snapshot time, and access list with the rehearsal evidence. A dry run should reduce migration risk without creating a new privacy problem.
Separate the rehearsal into observable stages
One long migration command is hard to diagnose. Break the process into stages that produce counts and evidence.
1. Capture the source state
Record the source snapshot identifier, extraction time, schema version, row counts, and relevant checksums. If the source continues changing, document whether the rehearsal uses a static export, a replication snapshot, or a change log that will be replayed later.
2. Load into an isolated destination
Run the migration against a destination that cannot send email, charge a payment method, publish content, or call live downstream integrations. Use separate credentials and endpoints. A migration rehearsal should not create production side effects while it is trying to imitate production behavior.
3. Transform and validate
Apply field transformations in a way the team can inspect. Capture rejected rows separately from successful rows. A row count alone is not enough: 100,000 rows loaded may still hide 3,000 rejected relationships or a default value applied to every missing field.
4. Reconcile source and destination
Compare totals, keys, relationships, required fields, status values, dates, and representative records. Reconciliation should explain expected differences, such as archived rows or normalized phone numbers, rather than treating every difference as a failure.
5. Exercise the application
Run the workflows that matter to users and operators. Search for a migrated record, edit it, create a related record, trigger a notification in a sandbox, export a report, and test permissions. A database can be structurally valid while the application still fails because it expects an old field name, a particular ID format, or a non-null value that the new schema permits.
Test rollback as a real procedure
A rollback plan that exists only in a document has not been tested. During the dry run, define the signal that stops the cutover and practice restoring the prior application state or switching traffic back to the old database.
Rollback may mean restoring a backup, reversing traffic, disabling a feature flag, replaying changes to the source, or keeping the old system read-only while the new system is corrected. The right method depends on the architecture and the direction of data flow. If new records can be created during cutover, the plan must account for those records. Losing them silently is not a rollback.
Measure the time and dependencies involved. Note which credentials are needed, who makes the decision, how users are informed, and how the team verifies that the rollback worked. This is also where teams discover that a backup exists but has never been restored, or that the fallback application version cannot run against the current infrastructure.
Common dry-run failures
- Only checking whether the script exits successfully. A successful process can still produce incorrect data. Add reconciliation and business-level checks.
- Using production credentials in a test environment. Separate credentials and block outbound side effects.
- Testing only clean records. Include nulls, long values, duplicate candidates, old records, and rejected cases.
- Comparing only row counts. Compare identities, relationships, field meanings, and expected exclusions.
- Ignoring application behavior. A schema test cannot replace user and operator workflow tests.
- Reusing a migration script without version control. Record the exact code, configuration, schema version, and input snapshot used in the rehearsal.
- Leaving the team without a decision log. Capture open issues, owners, due dates, approval status, and the evidence behind the decision.
Build a cutover scorecard
End the dry run with a short scorecard that someone outside the migration implementation can understand. Include the source and destination versions, duration by stage, source and destination counts, rejected and reconciled records, failed application checks, rollback results, unresolved risks, and the approval decision.
Use explicit outcomes such as approved, approved with documented follow-up, blocked, or needs another rehearsal. Avoid a vague “looks good.” The scorecard becomes a baseline for the final cutover and gives the team a way to notice when production differs from the rehearsal.
After launch, repeat the most important checks against the live destination. Compare the expected record totals, monitor errors and downstream jobs, verify representative user journeys, and keep the migration evidence with the release record. A dry run does not eliminate uncertainty, but it moves uncertainty into a place where the team can inspect and manage it.
Make the first cutover boring
The best database migration rehearsal is specific enough to expose assumptions before users do. It treats data mapping, application behavior, privacy, rollback, and operational ownership as one workflow.
DigitalWerks can help review a migration plan, define source-to-destination mappings, build reconciliation checks, test application workflows, and document a practical cutover and rollback process. Talk with DigitalWerks about making your next migration testable before it becomes urgent.