Scope a database migration review before production

Is the handoff ready?

Use these checks before access expands or the first ticket begins.

Separate the schema change from the data change

A database migration ticket often mixes two different risks: changing the structure of a table and changing the data inside it. The schema change may be reversible with a rollback script. A backfill or a destructive rename may not be. Split the ticket so the reviewer can see which part creates the irreversible boundary and who accepts it.

Ask the author to list every table, column, index, constraint. Job affected by the change. The list should distinguish additive changes from replacements and deletions. A column addition that allows nulls is not the same as a type change that rewrites every row, even when both appear in one migration file.

Write the compatibility window before deployment

A migration that runs while old and new application versions are both live needs a compatibility window. Record which version writes the old shape, which version reads the new shape. How long both must coexist. If the application cannot tolerate both shapes, the deployment order becomes part of the migration risk rather than an implementation detail.

The ticket should state the exact deploy order for the database, the application. Any background worker. It should also name the point at which the old code stops running. A reviewer who cannot see that sequence cannot judge whether the migration is safe to release during business hours.

Require a rehearsal on representative data

A migration that works on an empty development database may fail on production volume, constraints, or duplicate values. Require a rehearsal against a masked copy or a representative dataset with the same shape and roughly the same scale. Record the rehearsal date, the row counts, the runtime. Every error the author had to resolve.

The rehearsal should include the rollback or forward-recovery path, not only the forward migration. If the rollback script has never been executed, it is a plan rather than evidence. The reviewer should see the result of running it and the state of the data afterward. That check belongs in the require a rehearsal on representative data note, with the owner and the next action visible.

Define the stop and recovery conditions

Before release, name the conditions that would stop the migration: lock waits beyond a threshold, replication lag, failed constraint checks, or an unexpected row count. Record who can stop the job and who decides whether to roll back or continue forward. A stop condition that nobody is authorized to invoke is not a control. The define the stop and recovery conditions record should be dated and linked so a second reviewer can reproduce the result.

The recovery note should say what data may be lost, what must be restored from backup. How the team will verify that the application is healthy afterward. It should also state which steps are irreversible so a future incident reviewer does not assume a simple undo exists. That check belongs in the define the stop and recovery conditions note, with the owner and the next action visible.

Review the migration as an operations change

The code reviewer should not be the only approver. Include the person who owns the database, the person who owns the application release. The person who will respond if the migration fails. Each should confirm the part they are accountable for rather than giving a general approval to the ticket.

Record the approvals against the exact commit and the exact migration file. If the file changes after approval, the approval should be renewed. A migration review that points to an earlier commit is not evidence for the release that actually runs. That check belongs in the review the migration as an operations change note, with the owner and the next action visible.

Close with a post-migration check

After the migration, verify the row counts, constraints, application health. The queries that depend on the changed structure. Record the check time and the person who performed it. A successful migration command is not proof that the application still works.

If the check reveals a problem, preserve the evidence and route it through the recovery path rather than editing the migration history. The next review should use the finding to improve the rehearsal or the compatibility plan, not simply to add another approval box. That check belongs in the close with a post-migration check note, with the owner and the next action visible. The same check should be repeated when the migration plan changes, not only at the first release.

Make the migration observable during the window

The release should emit the signals the team needs to judge whether the migration is behaving as expected. Record the lock waits, replication lag, error rate, and row counts that will be watched, and name the person watching them. A migration that runs without observation is a change made blind, even when the script itself is correct. The make the migration observable during the window record should be dated and linked so a second reviewer can reproduce the result.

Set a short observation window after the migration before the team declares success. If the application depends on a background worker, include its queue depth and failure rate. The observation plan should say what normal looks like so an abnormal signal is not dismissed as noise. That check belongs in the make the migration observable during the window note, with the owner and the next action visible.

Keep the migration record with the release

Store the approved migration file, the rehearsal result, the deploy order, and the post-migration check with the release record. A future responder should not have to search three systems to understand what changed. Link the record to the incident or change process the client already uses. The keep the migration record with the release record should be dated and linked so a second reviewer can reproduce the result.

If the migration is later modified, preserve the earlier version and add the new approval. Overwriting the migration history destroys the evidence that the release was reviewed. The record should make the current state and the path to it equally visible. That check belongs in the keep the migration record with the release note, with the owner and the next action visible.

Agree on the definition of done

Define what the migration must prove before the release is closed. The definition may include row counts, constraint checks, application health, and a successful query against the new structure. Without that definition, the team can argue about success after the fact instead of checking a written standard. The agree on the definition of done record should be dated and linked so a second reviewer can reproduce the result.

The definition should be agreed before the migration runs, not written to match the result. If a check cannot be performed, record the gap and the owner who accepts it. That discipline makes the release decision easier and gives the next migration a reusable template. That check belongs in the agree on the definition of done note, with the owner and the next action visible.

Frequently asked questions

Sources

1. NIST SP 800-218, Secure Software Development Framework

   Supports planning, review, and verification of changes before release.

2. PostgreSQL documentation: ALTER TABLE

   Documents locking and rewrite behavior for structural changes.

3. GitHub Docs: About pull request reviews

   Supports review against a specific commit and recorded approval.