Snapshot models

Enterprise captures a portable schema model after migrate, publishes it as JSON, and lets CI run plan and preflight against that file — without opening the target database.

Enterprise captures a portable schema model after migrate, publishes it as JSON, and lets CI run plan and preflight against that file — without opening the target database.

--env still selects the overlay described in Environments. The snapshot is what that environment points at.

The snapshot loop

After every successful migrate, DBLift writes the schema model, the applied manifest with checksums, table stats and server info into the snapshots table on the deployment host. Publication is the last mile — getting that state out of the table and in front of CI.

# Deployment host
dblift migrate --env prod            # auto-capture writes the post-migrate snapshot
dblift snapshot publish --env prod   # writes prod.snapshot.json + prod.snapshot.manifest.json

# CI, no database access
dblift plan --env prod
dblift preflight --env prod --skip-replay

Point each environment at the artifact CI should read:

environments:
  prod:
    snapshot:
      source: file:.dblift/environments/prod.snapshot.json
      max_snapshot_age: 7d
  uat:
    snapshot:
      source: file:.dblift/environments/uat.snapshot.json
  staging:
    snapshot:
      source: db:            # CI with DB access reads the table

plan and preflight use that snapshot.source unless you pass --snapshot-model.

snapshot publish

dblift snapshot publish --env prod

What happens depends on the environment's snapshot.source:

SourceBehaviour
file:<path>Writes two files at the resolved path, creating parent directories as needed: <name>.snapshot.json, the payload in its unchanged format, and <name>.manifest.json, the integrity sidecar. --source=live-database forces a fresh capture instead of the post-migrate one.
db:Exits 0 as an intentional no-op. The table row already is the published state, so publish stays safe to run unconditionally across every environment in a pipeline.

Failures are actionable and non-zero: an unknown environment lists the configured names, and no configured source, an empty snapshot table, or a write failure each stop the run. --output <path> overrides the resolved path for debugging.

Publish the directory, not the file

Consumers verify what they read: plan and preflight check the payload against the sidecar manifest and honour max_snapshot_age. Check out the whole .dblift/environments/ directory in CI, not the single JSON file, or the manifest will not travel with it.

Creating a snapshot by hand

--output is optional and defaults to snapshot.json.

dblift snapshot --output .dblift/environments/prod.snapshot.json
dblift snapshot --source live-database --output snapshots/current.json
dblift --env production snapshot publish

Commit the reviewed model:

git add .dblift/environments/prod.snapshot.json
git commit -m "chore: refresh prod snapshot model"

What is in the model

A snapshot is the schema plus the applied-migration manifest, table stats, and server info. Plan and preflight consume that file in Enterprise. Pro diff compares applied migrations to the live schema via the internal snapshot table after migrate — diff --snapshot-model is not implemented and returns an explicit error.

See Plan, Preflight, Promote UAT → prod, or dblift snapshot.

DBLift is information technology / developer tools software. Contact: contact@dblift.com.