Database migration safety
A migration is waiting. Find the blocker before retrying
Repeatedly launching the same command can create more contention. Inspect the active database work and choose a controlled recovery action.
In this article
Confirm what is running
Check the migration tool's state and the database's active sessions. A terminal timeout does not always mean the server-side operation stopped.
Identify the command, its start time and whether it is waiting or doing work. Look for another migration instance before starting a replacement. Deployment retries can otherwise produce overlapping attempts.
Record the application impact. If ordinary requests are timing out, use the agreed stop procedure rather than waiting indefinitely for an apparently small schema change.
Trace the dependency
Inspect which session holds the conflicting lock and what transaction it belongs to. A session may appear idle while still holding an open transaction.
Determine the owner and purpose of that work. Terminating an unknown session can interrupt a legitimate business operation or trigger expensive rollback. Use the incident authority and database procedure appropriate to the service.
Distinguish a lock wait from slow execution. A large scan or index build needs a different response from a command that has not yet acquired its required lock.
Stop one operation deliberately
If cancellation is required, target the intended operation and confirm its final state. Avoid repeatedly cancelling and restarting without resolving the underlying condition.
Inspect the schema and migration history after cancellation. Depending on the command, there may be no change, a committed earlier step or an incomplete artefact requiring cleanup.
For PostgreSQL concurrent index creation, a failed attempt can leave an invalid index. Its existence alone is not evidence that the intended index is ready. Follow the documented repair procedure and verify validity before marking the step complete.
Resume with a bounded plan
Resolve the blocker or choose a suitable maintenance window. Apply the intended waiting limits and ensure only one migration coordinator runs.
Retry from the inspected state using a reviewed command. Confirm application health, the resulting schema and any background catch-up work afterwards.
Update the runbook with the actual cause and the evidence used to identify it. A useful incident record explains which transaction blocked which operation and how the retry became safe. Saying the migration was rerun successfully leaves the next operator with the same uncertainty.
Primary sources
PostgreSQL: explicit lockingPostgreSQL: CREATE INDEXReferences checked 11 September 2026.