dblift preflight

Run deployment preflight checks from a snapshot model. Preflight does everything plan does, then rehearses the migrations for real in a throwaway container — and optionally rehearses the rollback too. On Enterprise 3.4.0+, the same pending-set and placeholder flags as migrate apply; replay migrate and rehearse-rollback undo use that same subset and placeholder map.

Synopsis

$ dblift preflight (--container-image IMAGE | --container-existing NAME | --skip-replay)
                  [--snapshot-model PATH] [--max-snapshot-age AGE]
                  [--target-version VERSION]
                  [--tags TAGS] [--exclude-tags TAGS]
                  [--versions LIST] [--exclude-versions LIST]
                  [--placeholders K=V [K=V ...]]
                  [--container-runtime RUNTIME] [--container-name NAME]
                  [--container-env KEY=VALUE] [--container-env-file PATH]
                  [--container-port HOST:CONTAINER] [--container-wait-timeout N]
                  [--replay-scope {all,planned}] [--keep-container]
                  [--rehearse-rollback]
                  [--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, replay, and rollback-rehearse only up to this version

--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

--container-imageDocker image to start for migration replay

--container-existingName or ID of an already-running validation database container

--skip-replayRun plan and SQL validation without replaying migrations in a container

--container-runtimeContainer CLI backing --container-existing (default: auto-detect docker, then podman, then apple-container on PATH; also settable via DBLIFT_CONTAINER_RUNTIME, with this flag taking precedence)

--container-nameName for the managed Docker container

--container-envEnvironment variable for managed Docker container, KEY=VALUE; repeatable

--container-env-fileFile of env vars to pass to the validation container (docker --env-file)

--container-portPort mapping for managed Docker container, HOST:CONTAINER; repeatable

--container-wait-timeoutSeconds to wait for the validation database to become usable

--replay-scopeMigration replay scope: all for empty containers, planned for containers preloaded with history matching the snapshot (default: all)

--keep-containerDo not remove a managed validation container after preflight

--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 preflight output

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

--rehearse-rollbackAfter replay, also run undo migrations to verify rollback scripts work

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). Replay migrate and `--rehearse-rollback` undo use the same subset and placeholder map.

Rehearse only files tagged auth

$ dblift preflight --container-image postgres:16 --tags=auth

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

Examples

Rehearse the release in a fresh container

$ dblift preflight --container-image postgres:16 --container-port 55432:5432

Rehearse the rollback as well as the release

$ dblift preflight --container-image postgres:16 --rehearse-rollback --format text,html --output-dir dblift-reports

Run the checks without a container available

$ dblift preflight --skip-replay

Exit codes

CodeMeaning

0Command completed successfully

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

Previousplan Nextlicense