How to Dry-Run or Plan a Migration Before Applying

Generate and review the exact DDL a migration will run before it touches the database, so risky statements are caught in review.

A dry run or plan prints the SQL without applying it. Atlas can diff a desired schema against the current one to produce the migration; other tools have a plan or SQL-output mode. Emitting the plan in CI puts the DDL in front of reviewers before it runs anywhere.

Generate a plan per tool

# Atlas: diff desired schema vs a dev database
atlas migrate diff add_locale \
  --dir "file://migrations" \
  --to "file://schema.sql" \
  --dev-url "docker://postgres/16/dev"

# Flyway: print pending migrations without applying
flyway info

# Rails/Django output SQL without running it
bin/rails db:migrate:status
python manage.py sqlmigrate app 0007

Post the plan in CI

steps:
  - name: Show migration plan
    run: atlas migrate diff --dry-run --dir "file://migrations" \
      --to "file://schema.sql" --dev-url "docker://postgres/16/dev"

Gotchas

• A dry run against an empty dev database can miss data-dependent problems; test against realistic data too.
• Atlas diff needs a scratch dev database to compute the plan; the service container is a good fit.

Related guides