atlas schema apply: Usage, Options & Common CI Errors
atlas schema apply migrates a database to match a desired schema declaratively.
atlas schema apply brings a database in line with a declared HCL/SQL schema in CI. The two things that trip pipelines are the interactive approval prompt and the required dev database for planning.
What it does
atlas schema apply computes the diff between a target database (--url) and a desired schema (--to) and applies the SQL to reconcile them. It uses a throwaway dev database (--dev-url) to plan and validate the migration safely.
Common usage
atlas schema apply --url "postgres://postgres:secret@localhost:5432/app?sslmode=disable" --to file://schema.hcl --dev-url "docker://postgres/16/dev"
atlas schema apply --url "$DB_URL" --to file://schema.sql --auto-approve
atlas schema apply --url "$DB_URL" --to file://schema.hcl --dry-run
atlas schema apply --env localOptions
| Flag | What it does |
|---|---|
| --url <uri> | Target database to modify |
| --to <source> | Desired schema (file://, db url, ...) |
| --dev-url <uri> | Dev database used to plan/validate |
| --auto-approve | Apply without the interactive prompt |
| --dry-run | Print the SQL without applying it |
| --env <name> | Use a named env from atlas.hcl |
Common errors in CI
atlas waits at an interactive "Are you sure?" approval and the non-interactive job hangs - pass --auto-approve (or --dry-run for plan-only) in CI. "Error: connecting to dev database ... " means --dev-url is missing or unreachable; atlas needs it to plan, and docker:// dev URLs require Docker. Destructive changes (dropping a column/table) are flagged and may be blocked by lint rules - review the plan or set the policy explicitly rather than forcing them blindly.