atlas migrate diff: Generate a Migration
atlas migrate diff generates a new versioned migration by diffing the desired schema against the current migration state.
diff is an authoring command that needs a scratch dev database. CI usually verifies the directory is in sync rather than generating new migrations.
What it does
atlas migrate diff compares the desired schema (from --to, e.g. an HCL/SQL schema or a live database) against the state produced by replaying the existing migrations on the --dev-url database, and writes a new migration file plus an updated atlas.sum.
Common usage
atlas migrate diff add_users \
--dir "file://migrations" \
--to "file://schema.sql" \
--dev-url "docker://postgres/16/dev"
# CI: verify no drift, i.e. diff produces nothing
atlas migrate diff --dir "file://migrations" --to "file://schema.sql" \
--dev-url "docker://postgres/16/dev"Options
| Flag | What it does |
|---|---|
| --dir <url> | Migration directory to extend |
| --to <url> | Desired schema source (HCL, SQL, or a database URL) |
| --dev-url <url> | Scratch database used to compute the diff |
| --format <tmpl> | Output format for other tools |
In CI
A common gate runs migrate diff with the same schema and fails if it produces a new file, proving the committed migrations match the declared schema. The --dev-url dev database must be reachable in CI; the docker:// form spins one up if Docker is available on the runner.
Common errors in CI
"connecting to dev database" errors mean --dev-url is unreachable or Docker is unavailable on the runner. "checksum mismatch" against atlas.sum means files changed without atlas migrate hash. If diff unexpectedly generates a migration in CI, the schema and migrations have drifted and need reconciling.