dblift plan compares local migration scripts with a DBLift snapshot. It does not connect to the target database, create the history table, or execute SQL. This makes it suitable for CI jobs where the database is not reachable.
Run a plan
The snapshot input comes from the active environment: --env selects the environment and its snapshot.source names the published artifact.
dblift plan --env prod --format json --fail-on error--snapshot-model remains the explicit override and takes precedence over the environment's source.
What a plan reports
- pending versioned migrations
- repeatable migrations whose checksum changed or that are missing from the snapshot
- checksum drift for already-applied versioned migrations when the snapshot contains checksums
- SQL validation results for planned SQL scripts
The HTML artifact carries the full findings table and prints to white.
Zero-downtime rewrites
When a migration contains dangerous DDL, the plan also proposes a lock-friendly way to run it. The advisory arrives as an informational plan.safe_rewrite finding carrying ordered steps and the rendered SQL — the same expand/contract script diff --generate-sql would emit. It never gates the build.
| Phase | What it does |
|---|---|
| EXPAND | Additive and backward-compatible. Deploy now. |
| BACKFILL | Batched, repeatable DML that populates the new state. |
| CONSTRAIN | Add constraints once the new state is populated. |
| CONTRACT | Drop the old shape after readers have moved. |
| ADVISORY | Informational only. A plan that is 100% advisory does not fail the build. |
See zero_downtime for batch size and backfill style.
Exit and formats
--fail-on error (the default) exits non-zero only on errors. --fail-on warning treats warnings as blocking. Formats: text, html, json, sarif, github-actions, gitlab, compact. Use --output for one file or --output-dir for timestamped plan-report-{YYYYMMDDTHHMMSSZ}.{ext} files. --validate-scope pending|all and --skip-validate-sql control SQL lint during the plan. --max-snapshot-age refuses a stale snapshot. If snapshot.source is db:, plan opens the database — that is the exception to the offline default.
dblift plan --env prod --format json,html --output-dir dblift-reports --fail-on errorSee dblift plan for flags, Reading a report for the HTML, and Preflight for the connected rehearsal.