Docker and Compose
Run database migrations safely with Docker Compose
Use one-shot migration jobs, compatible schema changes and clear failure handling instead of every replica racing at startup.
By AppLaunch Editorial · Reviewed 2026-08-25
Direct answer
Run migrations as an explicit one-shot release step with the same application image and a single owner. Prefer backward-compatible expand-and-contract changes so old and new application versions can overlap or roll back safely.
What this means in plain English
A database migration changes tables or stored information for a new app release. Run it as one controlled job, not from every web container at once. If three replicas all try the same change, they can conflict or repeat work.
Safer releases add the new structure first, deploy code that understands both old and new shapes, move data in manageable batches and remove the old structure later. This leaves a period when the application can roll back without finding a database it no longer understands.
Who should run the migration?
| Execution | Exactly one controlled migration job |
|---|---|
| Compatibility | Old and new code tolerate transitional schema |
| Failure | Deployment stops and exposes logs/status |
A simple example
A column needs a new name. The release first adds the new column, then code writes to both and reads the new one. After data is copied and the rollback period ends, a later release removes the old column. Nothing depends on one irreversible moment.
What to do, step by step
1. Back up or confirm recovery before destructive changes.
Start here before buying anything or changing several settings at once. It gives you a clear starting point based on execution: exactly one controlled migration job. Write the result down so you can compare it later.
2. Apply additive schema first.
Use the same files, versions and settings that the real project will use. A quick test with an empty or different setup can look successful while completely missing the problem you are trying to solve.
3. Deploy code that supports both shapes.
Try the busiest realistic situation, not the easiest one. Include the people, data, traffic or background work you genuinely expect, then watch for slowdowns and errors rather than relying on a single headline number.
4. Remove old columns only after rollback window closes.
Finish by checking the result against failure: deployment stops and exposes logs/status. Keep the old setting or release available until you know the change works and can be reversed safely.
One more useful tip
Treat a failed migration as a stopped release with visible logs. An endless restart loop can repeat partial changes and make the original problem harder to understand.
Common mistakes and how to avoid them
Every web replica runs migrations.
This gives a misleading or unsafe result because it leaves out execution. A better approach is to back up or confirm recovery before destructive changes, then check the result before making the change permanent.
Combining irreversible deletion with first deploy.
This gives a misleading or unsafe result because it leaves out compatibility. A better approach is to apply additive schema first, then check the result before making the change permanent.
Restart-looping a failed migration.
This gives a misleading or unsafe result because it leaves out failure. A better approach is to deploy code that supports both shapes, then check the result before making the change permanent.
Words explained
- image
- The read-only package used to create a container. A good production image can be rebuilt and traced back to a specific release.
- Compose
- Docker Compose is a file-based way to describe several containers, their settings, storage and networks as one application.
Quick checklist
- Back up or confirm recovery before destructive changes.
- Apply additive schema first.
- Deploy code that supports both shapes.
- Remove old columns only after rollback window closes.
Common questions
What is the simple answer?
Run migrations as an explicit one-shot release step with the same application image and a single owner. Prefer backward-compatible expand-and-contract changes so old and new application versions can overlap or roll back safely.
What should I check first?
Start with execution: exactly one controlled migration job. That is usually more useful than choosing from a marketing label or copying somebody else’s setting.
How can I make the change safely?
Back up or confirm recovery before destructive changes. Then change one thing at a time, keep a backup or old version, and use the same real-world test after each change.
What is the easiest mistake to avoid?
Every web replica runs migrations. Avoiding that one mistake makes the rest of the comparison much more trustworthy.