dblift plan

Build an offline migration plan from a snapshot model. Plan never connects to the target database — it reads a snapshot and your migration scripts, and reports what a release would run. On Enterprise 3.4.0+, the same pending-set and placeholder flags as migrate apply. For how to read the result, see Plan.

Synopsis

$ dblift plan [--snapshot-model PATH] [--max-snapshot-age AGE]
             [--skip-validate-sql] [--validate-scope {pending,all}]
             [--target-version VERSION]
             [--tags TAGS] [--exclude-tags TAGS]
             [--versions LIST] [--exclude-versions LIST]
             [--placeholders K=V [K=V ...]]
             [--format FORMAT[,FORMAT...]] [--fail-on LEVEL]
             [--output PATH] [--output-dir DIR]

Options

FlagDescription

--snapshot-modelPath to the DBLift snapshot model representing the target environment state (explicit override; when omitted, the active environment's snapshot.source is used — select with --env / DBLIFT_ENV)

--target-versionPlan only up to this version; later pending migrations are omitted

--tagsInclude migrations with these tags (comma-separated)

--exclude-tagsSkip migrations with these tags (comma-separated)

--versionsInclude only these versions (comma-separated)

--exclude-versionsSkip these versions (comma-separated)

--placeholdersSQL placeholders for variable substitution in migration scripts. Format: key1=value1,key2=value2 or key1=value1 key2=value2. Can be repeated: --placeholders k1=v1 --placeholders k2=v2

--max-snapshot-ageOpt-in freshness gate (e.g. 7d, 24h): fail (per --fail-on) when the snapshot is older; overrides snapshot.max_snapshot_age from the config

--skip-validate-sqlDo not run SQL validation on planned migration scripts

--validate-scopeSQL validation scope (default: pending)

--formatReport format(s): text, json, html, sarif, github-actions, gitlab, compact; comma-separate values to write multiple artifacts

--fail-onMinimum finding severity that makes the command fail (default: error)

--outputOptional file path for text, JSON, or HTML plan output

--output-dirDirectory for timestamped report artifacts when multiple formats are requested

Filters

Enterprise 3.4.0+: the same pending-set as migrate. `--tags` is comma-separated from the filename `[tag,...]`. Version-less repeatables are not dropped by `--target-version` / `--versions` / `--exclude-versions`; `--tags` / `--exclude-tags` can still exclude them. Checksum drift on already-applied scripts is always reported. `--placeholders` is substitution, not a pending-set filter (yaml `placeholders:` then CLI overlay, repeatable `key=value`); checksums stay unsubstituted (file as committed). `--validate-scope all` still lints every local SQL script; default `pending` lints the filtered pending set.

Plan only files tagged auth

$ dblift plan --tags=auth

Global flags apply to every command: --config, --env, --scripts, --dry-run, --quiet, --log-level. See global flags.

Examples

Plan against the active environment's configured snapshot

$ dblift --env production plan

Produce the three evidence artifacts an approver reads

$ dblift plan --format text,json,html --output-dir dblift-reports

Refuse to plan against a snapshot older than a week

$ dblift plan --snapshot-model prod-snapshot.json --max-snapshot-age 7d

Exit codes

CodeMeaning

0Command completed successfully

4A paid-edition feature was invoked without a valid licence (EXIT_LICENSE_REQUIRED)

Previoussnapshot Nextpreflight