# Hand over the migration's unfinished state explicitly

A paused backfill or retained old column is part of the running system. Give the next team the evidence and authority to finish it safely.

By Cobnex editorial. Published 2026-09-10. Updated 2026-09-11.

## Describe the current phase

State which schema changes are complete, which application versions are deployed and which representation is authoritative. Include whether readers have switched and whether older code remains a supported rollback option.

Avoid a single label such as migration deployed when data movement or cleanup is still pending. The receiving team needs to know what remains active, not just which release ran.

Keep the migration identifier and reviewed script version with the record so an operator can reproduce the intended procedure.

## Preserve progress and exceptions

Document where the backfill stores its checkpoint and how it selects remaining work. Explain how conflicts, rejected values and deleted records affect the completion count.

Provide a query or supported report that distinguishes pending rows from intentionally empty values. A maintainer should not have to infer progress from a timestamp in an old terminal log.

List unresolved data exceptions with their business owner. Technical staff should not invent replacement values simply because a migration cannot finish without a decision.

## Explain pause, resume and rollback

Give the receiving team a controlled way to pause processing and confirm that it has stopped. Document what happens to an in-flight batch and how retry avoids repeating harmful work.

State the monitoring thresholds that should trigger a pause, including application impact and storage headroom. The runbook should connect each threshold to an action.

Describe rollback in terms of data and supported code versions. If a destructive step has occurred, say which recovery process now applies rather than leaving an obsolete rollback command in the document.

## Assign the final cleanup

Name the owner and conditions for removing old columns, temporary tables, grants and compatibility code. Include any scheduled consumer that must run successfully first.

Ask the receiving team to locate the current phase, inspect remaining work and rehearse a pause and resume in a safe environment. Resolve gaps in access or documentation before closing the handover.

A migration can outlast the team that started it. Clear ownership of its intermediate state prevents a temporary compromise from becoming a permanent and poorly understood part of the database.

## Sources

- [PostgreSQL: progress reporting](https://www.postgresql.org/docs/17/progress-reporting.html)