Before removing a migration service from a Docker Compose setup, you need to verify that the migration has fully completed, that no other service depends on it at startup, and that your data is backed up. This article walks through the exact checks to perform so you don’t break your application or lose data.
Background: Why Migration Services Exist
Database migrations are scripts that change your database schema—adding a column, creating a table, or backfilling data. In a Docker Compose environment, these are often run as a separate service that starts before your main application. The service runs the migration command (e.g., alembic upgrade head, prisma migrate deploy, or django migrate) and then exits. Compose’s depends_on with condition: service_completed_successfully ensures the app only starts after the migration finishes.
Once the migration is stable, many teams remove the migration service to simplify the Compose file and reduce startup time. But doing this too early can leave your app pointing at an un-migrated database.
How Init Containers Work in Docker Compose
Compose itself doesn’t have a native “init container” concept like Kubernetes. Instead, you create a regular service that runs a one-off command. A typical example:
services:
db:
image: postgres:16
migrate:
image: myapp:latest
command: ["alembic", "upgrade", "head"]
depends_on:
db:
condition: service_healthy
app:
image: myapp:latest
depends_on:
migrate:
condition: service_completed_successfully
The migration service runs, exits with code 0 on success, and Compose starts the app. If the migration fails, the app never starts. This pattern is reliable but adds a step to every docker compose up.
What to Check Before Removing the Migration Service
Removing the service means the migration will no longer run automatically. You must be certain the database is already in the correct state. Go through this checklist:
- Verify the migration has run successfully on the target database. Check the migration tracking table (e.g.,
alembic_version,_prisma_migrations, or Django’sdjango_migrations) and confirm the latest revision is present. - Confirm no pending migrations exist. Run the migration command manually against a copy of the production database and see if it reports “no new migrations”.
- Check your app’s startup behavior. If your application itself runs migrations on boot (common with Django’s
migratein entrypoint scripts), removing the separate service is safe. If it doesn’t, you’ll need to run migrations manually after each deployment. - Review all
depends_onreferences. If any other service references the migration service, you must remove those references too, or Compose will error. - Back up the database before removing the service, so you can restore if something unexpected happens.
- Test in a staging environment that mirrors production. Remove the service there first and confirm the app starts and functions.
Common Problems After Removal
The most common issue is that the application starts but fails because the schema is outdated. This happens when a new migration is added later and no one remembers to run it manually. Another problem is that docker compose up fails with an error like service "migrate" is undefined if you forget to remove references in depends_on.
There’s also the race condition: if you remove the migration service but your app’s entrypoint doesn’t wait for the database to be ready, the app may crash on first boot. Even with depends_on, Compose only waits for the container to start, not for the database to accept connections. Use a health check on the database and condition: service_healthy to avoid this.
How to Choose: Keep or Remove
Decide based on your deployment workflow:
- Keep the migration service if you deploy directly with
docker compose upon the server and want zero manual steps. It’s also safer for teams where multiple people might deploy. - Remove it if you use an external CI/CD pipeline that runs migrations as a separate step before deploying the app. Many teams prefer this because it gives more control and avoids running migrations on every container start.
- Consider a hybrid: keep the migration service but only run it explicitly with
docker compose run --rm migratewhen needed, rather than as part of the defaultup.
If you remove it, document the manual migration step in your README or deployment script. A forgotten migration is a common cause of production outages.
Safety Measures and Best Practices
Before and after removal, follow these safety practices:
- Always take a database backup before any schema change or removal of migration automation.
- Use a read-only user for the app’s database connection if possible, so the app cannot accidentally alter the schema.
- Set a timeout on the migration command in CI, so it fails loudly instead of hanging.
- Monitor your database error logs after deployment to catch any schema-related issues early.
- Keep the migration files in your repository even after removing the service—you’ll need them for future changes.
Alternatives to a Separate Migration Service
If you’re removing the service because it feels clunky, consider these alternatives:
- Run migrations in the app’s entrypoint. Many frameworks (Django, Rails) support this, but it can cause issues if multiple app replicas start simultaneously—they may race to run the same migration.
- Use a dedicated migration tool like Flyway or Liquibase, which can be invoked from a CI job.
- Use Kubernetes Jobs if you’re on Kubernetes, which are the proper equivalent of init containers.
- Use an orchestration tool like Ansible or Terraform to run migrations as part of your provisioning process.
Frequently Asked Questions
How do I know if my migration has actually run?
Check the migration tracking table in your database. For Alembic, run alembic current; for Prisma, check _prisma_migrations; for Django, run python manage.py showmigrations. The latest revision should be marked as applied.
What happens if I remove the migration service and then add a new migration?
You’ll need to run the migration manually before deploying the new app version. If you don’t, the app will fail when it tries to query a column or table that doesn’t exist. Make it a step in your deployment pipeline.
Can I keep the migration service but not run it on every up?
Yes. You can define the service but not have it as a dependency of the app. Then run it explicitly with docker compose run --rm migrate when you need to migrate. This gives you control without removing the service entirely.
Is it safe to rely on the app’s own migration on startup?
It’s safe for a single-instance app, but risky if you scale to multiple replicas. Two app instances might run the same migration concurrently, causing conflicts. Use a locking mechanism or keep a separate migration step.
What should I do if the migration service is already removed and the app won’t start?
First, check the database schema against your app’s expected schema. If a migration is missing, run it manually using the same command the service used. Then restart the app. Always have a backup to restore if needed.
Does depends_on wait for the migration to finish?
Only if you use condition: service_completed_successfully. The default depends_on just waits for the container to start, not for the command to succeed. Always specify the condition to be safe.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Skip Ryobi and Milwaukee? Harbor Freight Tools to Buy
- Funny Subreddits That Make You Laugh
- Why Retro Gaming Is Still Worth Playing Today
- Neptune Facts That Will Blow Your Mind
- Survival Crafting Game Fatigue: Why & How to Fix It
- Sell Your EV Now Before Prices Plummet?