---
title: "What to check in a database migration"
description: "What to check in a database migration: expand and contract, breaking changes, staged rollout, and a tested rollback."
canonical: "https://goodcodereview.com/guides/what-to-check-in-a-database-migration"
updated: "2026-11-06"
---

# What to check in a database migration

A database migration review asks whether old and new code can both run against the schema while the change rolls out, and whether you can undo it. These stable checks cover the schema change, the rollout, and the way back.

## The checks

- [`sys-migration-expand-contract`](https://goodcodereview.com/system.md#sys-migration-expand-contract) [block]: Run data backfills in batches, in a migration separate from the schema change.
- [`chg-expand-contract`](https://goodcodereview.com/change.md#chg-expand-contract) [block]: Evolve shared contracts in steps: add the new form beside the old (expand), migrate every consumer, then remove the old form (contract) in a later change.
- [`chg-breaking-change-taxonomy`](https://goodcodereview.com/change.md#chg-breaking-change-taxonomy) [block]: Treat any change that callers can observe in a signature, return values, error types, defaults, or side effects as breaking until a consumer check says otherwise.
- [`chg-tests-ship-with-change`](https://goodcodereview.com/change.md#chg-tests-ship-with-change) [block]: Ship new or changed behaviour in the same change as a test that fails if the behaviour breaks.
- [`prod-canary-staged-rollout`](https://goodcodereview.com/production.md#prod-canary-staged-rollout) [block]: Roll out in stages behind a canary, and abort by rule, not by judgment.
- [`inc-rollback-path-tested`](https://goodcodereview.com/incident.md#inc-rollback-path-tested) [should-fix]: Exercise each mitigation that a runbook names (rollback, failover, flag off) on a regular schedule.

## Run them

To run these checks, paste `Read https://goodcodereview.com/llms.txt and use it to review my code.` to your agent, or work through them by hand. Start with the [change level](https://goodcodereview.com/change.md) for a migration in a diff, and the [system level](https://goodcodereview.com/system.md) for the design.