Control a database migration handoff between shifts

Is the handoff ready?

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

Record the migration state before the handoff

A migration handoff should begin with the current state of the schema, not a summary of what the engineer intended. Record the migration version applied to each environment, the pending scripts, and the checks that have run. Note the exact commit and the database snapshot used for the last rehearsal. The next engineer should be able to see whether the change is half-applied, fully applied, or still only planned.

Separate the schema state from the application state, because a migration can be applied before the code that depends on it is deployed. Record which application version expects the new schema and whether that version is live. A handoff that says the migration is done without naming the application state can cause a deploy to fail. Use one shared record for both states.

Keep the rollback path executable

A rollback plan is only useful if the next engineer can run it without reconstructing the original environment. Write the exact commands, the backup location, and the expected duration. Test the rollback in a staging copy and record the result. If the rollback depends on a person or a credential, name them and confirm availability before the handoff.

Distinguish a reversible migration from one that destroys data. A column drop or a type change may not be reversible without a backup, so the handoff should state the backup time and the retention period. Do not describe a destructive change as reversible just because a down script exists. The reviewer should see the data consequence in plain language.

Name the next decision and owner

The handoff should end with the next decision, the person who will make it, and the time by which it is needed. The decision might be to proceed to production, to run a second rehearsal, or to pause for a data check. Write the question in one sentence so the next engineer does not have to infer it. A migration that waits for an unnamed approval is a migration that will be rushed later.

If the decision requires a business owner, include the evidence that owner needs. A schema change that affects reporting may need a finance review, while a change that affects access may need a security review. Record the review status and the contact. The next shift can then follow up with the right person instead of guessing.

Test the handoff with a second engineer

Before the handoff, ask a second engineer to read the record and explain what they would do next. If they cannot state the current version, the rollback command, and the next decision, the record is incomplete. Fix the record before the original engineer goes offline. The test should use the same systems the next engineer will actually use.

Run one dry-run command from the record in a non-production environment and confirm that the output matches the note. A command that works on the author's machine but fails in the shared environment is not a handoff. Record the result of the dry run and the time it was performed. That evidence gives the next shift confidence to act.

Freeze unrelated schema changes

During a migration window, unrelated schema changes should wait. Two migrations that touch the same table can interact in ways that neither author anticipated. Publish the freeze window and the tables it covers. Ask the team to route new schema requests to the migration owner until the window closes.

If an unrelated change cannot wait, review it with the migration owner before it is applied. Record the decision and the new sequence. Do not let a routine change slip in because it looks small. The freeze is a coordination tool, not a punishment, and it should end when the migration is verified.

Verify the destination after the handoff

The receiving engineer should verify the destination state rather than trusting the note. Check the migration table, the schema version, and one application query that depends on the change. Record the verification time and the result. A handoff is not complete until the next person has observed the state for themselves.

If the verification fails, stop and return to the last known good state. Do not attempt a second migration on top of an unverified first one. Record the failure, the rollback action, and the owner who decided to stop. The record should make the recovery path obvious to the next person.

Review the handoff after the window

After the migration window, review the handoff record with both engineers. Ask which field was most useful and which was missing. Check whether the rollback was tested and whether the destination verification caught anything. Record one change to the template for the next migration.

Compare the actual duration with the estimate and the actual data impact with the plan. A migration that took twice as long may indicate an untested dependency rather than a slow engineer. Update the estimate method and the rehearsal checklist. The next handoff should be easier to verify, not longer to read.

Frequently asked questions

Sources

1. NIST Secure Software Development Framework

   Authoritative guidance used to frame this field guide.

2. CISA Secure by Design

   Authoritative guidance used to frame this field guide.

3. OpenTelemetry documentation

   Authoritative guidance used to frame this field guide.