Troubleshooting · By Rivtor · Updated
Troubleshoot a failed database migration during deployment
Read the first meaningful migration error and confirm the target database before retrying. Missing credentials, inconsistent migration history and destructive schema changes need different repairs.
See the Rivtor deployment workflow →
Locate the failing stage
Dependency installation, migration execution and server startup are separate stages. Read the failed deployment build log rather than only the currently running app’s logs. Preserve the revision identifier and relevant error without copying connection credentials into a public issue.
Compare history with actual schema
Check that every revision file was committed and dependencies form a complete chain. Determine whether another process already applied part of the change. Marking a revision as applied without checking the database can leave the recorded history inconsistent with the real schema.
Assess the effect on data
Adding a nullable column is different from dropping a table or rewriting a large index. Review recovery options before a destructive operation. Do not infer arbitrary point-in-time recovery from a general backup claim. Application rollback does not necessarily undo a migration.
Retry with a bounded procedure
Test a repair against an isolated database with synthetic data. Apply the documented release procedure, then verify application reads and writes. If the migration partially completed, plan a corrective forward migration or recovery rather than blindly replaying the original command.
Command reference
npx rivtor logs --build DEPLOYMENT_ID
These commands illustrate the documented workflow. Replace example addresses and identifiers with your own. Deployment and migration commands affect the selected project; confirm the target before running them.
Classify the first useful error
| Symptom | Investigate first | Avoid |
|---|---|---|
| Cannot connect | Target, network, credentials and driver | Repeating a schema command blindly |
| Missing revision | Committed history and deployed artifact | Deleting production migration records |
| Existing table or column | Actual schema versus migration history | Assuming a fresh empty database |
| Data constraint failure | Existing rows and planned backfill | Discarding customer records |
Capture the migration tool's version, revision identifiers and failing statement without exposing connection credentials. Verify which database is selected before attempting a repair.
Rehearse a compatible recovery
Take a recovery point using the data platform's documented procedure, then test restoration on a separate destination. A backup's existence alone does not establish that a particular recovery will succeed.
For a change requiring a new non-null field, consider adding the field compatibly, backfilling existing rows and applying the constraint in a later release. Review whether the old application remains compatible during that sequence.
Separate deploy rollback from data rollback
Rolling application code back does not necessarily reverse schema changes. A destructive migration may need a reviewed data-recovery procedure rather than a down migration. Preserve the last working application while diagnosing the candidate release.
Consult the relevant workflow: Prisma and Next.js, FastAPI and Alembic, or Django and Postgres. Sources: Alembic tutorial and Prisma production migrations.
Next steps
Read the Rivtor reference for supported configuration and limitations, and use the deployment quickstart when trying Rivtor for the first time. Validate workflows with synthetic data before connecting valuable production records.