dblift diff

Compare applied migrations against the live database schema. Diff reports what the database has that your migrations do not describe, and can generate the SQL to close the gap — with a reverse script and impact annotations alongside it. Enterprise `--desired-model` diffs a model file; `--base` compares that model to a published snapshot.

Synopsis

$ dblift diff [--target-version VERSION] [--ignore-unmanaged]
             [--desired-model FILE [--base PATH] [--allow-drops [--approved-by NAME]]
                             [--max-snapshot-age AGE]]
             [--generate-sql [--output-file PATH] [--no-undo] [--no-impact]
                             [--fail-on LEVEL] [--impact-format FORMAT]
                             [--impact-output PATH] [--batch-size N]]
             [--tags TAGS] [--exclude-tags TAGS]
             [--versions LIST] [--exclude-versions LIST]
             [--strict] [--table TABLE] [--snapshot-table TABLE]

Options

FlagDescription

--tableCustom schema history table name (default: dblift_schema_history)

--snapshot-tableCustom schema snapshot table name (default: dblift_schema_snapshots)

--strictEnable strict mode - fail if any previously applied migration is missing and require migrations to be applied in strict version order

--tagsExecute migrations with specified tags (comma-separated list)

--exclude-tagsSkip migrations with specified tags (comma-separated list)

--versionsExecute only specific versions (comma-separated list)

--exclude-versionsSkip specific versions (comma-separated list)

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

--target-versionCompare migrations up to this version

--desired-modelDiff the live database against this model file taken as the desired state; with --generate-sql, renders the migration that makes the database match the model (ENTERPRISE)

--snapshot-modelNot supported on diff — use --desired-model (on plan and preflight this flag means the current target-environment state, which is the opposite)

--baseWith --desired-model, compare against this published snapshot instead of the live database (the comparison itself opens no connection; the command still probes the database for report metadata, best-effort)

--ignore-unmanagedHide unmanaged objects section (objects not in migrations)

--allow-dropsWith --desired-model, include DROP statements for objects the model omits. Off by default: a model can be stale, so 'absent from the model' is not evidence of 'meant to be dropped'.

--max-snapshot-ageWith --desired-model, refuse the model when its recorded captured_at is older than this (e.g. 7d, 24h); overrides snapshot.max_snapshot_age from the config. Same freshness gate as plan/preflight; the checksum is not verified on this path.

--approved-byName of the person approving a drop of a protected object class (tables, columns). Recorded in dblift-manifest.json. It is never validated as an identity and never treated as authentication.

--generate-sqlGenerate SQL script to synchronize schemas based on detected differences (also emits a paired reverse/undo script by default; see --no-undo)

--no-undoWith --generate-sql, do not also generate the reverse (undo) script

--output-fileOutput file path for generated SQL script (requires --generate-sql). The undo script is written alongside it (V*__.sql → U*__.sql, else *.undo.sql)

--no-impactWith --generate-sql, do not annotate the generated script with lock/duration/risk impact estimates

--fail-onWith --generate-sql, minimum impact risk severity that makes the command fail (default: no gating); only the forward script gates

--impact-formatWith --generate-sql, output format for the impact report (default: console)

--impact-outputWith --generate-sql, optional file path to write the impact report to

--batch-sizeWith --generate-sql, rows per pass for the PK-keyed batched backfill UPDATE in a SET NOT NULL safe rewrite (default: 5000)

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

Examples

See what the database has that your migrations do not

$ dblift diff

Generate a sync migration and its reverse

$ dblift diff --generate-sql --output-file migrations/V2_4_0__sync_schema.sql

Fail the build if the generated script carries warning-level risk

$ dblift diff --generate-sql --fail-on warning --impact-format sarif --impact-output results.sarif

Exit codes

CodeMeaning

0Command completed successfully

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

Previousmcp Nextexport-schema