database-migration

Database Migration

Detection

Check for migration tooling in the project:

Migration Commands

When to Run Migrations

Pre-deploy (before new code runs)

Use when: new code REQUIRES the schema change to function.

• Run migration as a separate step before deploying the new container
• If migration fails, abort deployment — don't start the new container
• Compose: use a migrate service with depends_on before the app service

Post-deploy (as part of container startup)

Use when: migration is additive (new columns/tables) and old code wouldn't break.

• Include migration command in Dockerfile CMD or entrypoint script
• Risk: if migration fails, the container may crash-loop
• Advantage: simpler deployment pipeline

Recommended patterns by framework

Compose Migration Service

For compose deployments, add a migration service that runs before the app:

services:
  migrate:
    build: .
    command: npx prisma migrate deploy
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  app:
    build: .
    depends_on:
      migrate:
        condition: service_completed_successfully
      db:
        condition: service_healthy

Entrypoint Script Pattern

When migrations run at container startup:

#!/bin/sh
set -e

echo "Running migrations..."
npx prisma migrate deploy

echo "Starting application..."
exec node dist/index.js

Key: use exec for the final command so the app process becomes PID 1 and receives signals correctly.

Safe Migration Practices

• Always use migrate deploy / migrate:latest (not push or sync) — deploy applies migration files in order; push/sync can be destructive
• Never run migrations interactively — all migration commands must work non-interactively in Docker
• DATABASE_URL must be set — migrations need the production database connection, not a build-time placeholder
• Additive-first: add new columns as nullable or with defaults before deploying code that requires them
• Separate schema changes from data changes — schema migrations in deploy pipeline, data backfills as separate tasks
• Test migrations against a copy before running on production when possible

Gotchas

• Prisma migrate deploy vs db push: deploy applies migration files; push syncs schema directly (destructive, dev-only)
• Django migrate with --run-syncdb can create tables without migration files — avoid in production
• TypeORM synchronize: true in production drops and recreates tables — ensure it's disabled
• Alembic autogenerate may miss some changes (custom types, triggers) — always review generated migrations
• Rails db:schema:load vs db:migrate: schema:load replaces all migrations with a single schema load — only use for new databases
• EF Core Update-Database in Package Manager Console is interactive — use dotnet ef database update for Docker

Related Skills

• pre-deploy-checklist — Detects migration tools and checks if migration command is in the deploy flow
• rollback-strategy — Guidance on rolling back when migrations make rollback risky
• compose-setup — Migration service pattern for compose deployments