Evidence Artifacts
Every run leaves files behind. Some are for a human approver, some for a parser, and two live in the database itself. This page names each one, where it lands, and what it proves.
What a run produces
| Artifact | Where it lands | What it proves |
|---|---|---|
| Run log | log_dir | Every step of the run, in the order it happened. Written for text, JSON or HTML depending on the configured format. |
| Migration report | log_dir · HTML | What actually ran, statement by statement, and how long each took. OSS. |
| validate-sql report | --output · HTML or SARIF | Which policy rules the SQL broke and where. Pro command; packs and profiles are Enterprise. |
| Plan report | --output · HTML | What is pending against a snapshot, and whether anything drifted. Enterprise. |
| Preflight report | --output · HTML | Whether the release is ready, including a rehearsed replay. Enterprise. |
| Schema snapshot | .dblift/environments/ | The schema state a plan or preflight was judged against. Also recorded in dblift_schema_snapshots. |
| Undo script | migrations/ | That a migration was reversible before it was applied — not after. |
| History table | dblift_schema_history | Which version was applied, when, by whom, with what checksum. The one artifact you cannot lose. |
Evidence is a by-product, not a request
Nothing here is generated on request after the fact. Evidence is a by-product of the run that produced it, which is what makes it evidence — a report written later cannot describe a database state that has already moved on.
Filenames carry the run
OSS logs and migrate reports are named from schema, database, command and timestamp:
Dblift_<schema>_<database>_<timestamp>.logDblift_<schema>_<database>_<command>_<timestamp>.html
Plan and preflight write a different pattern when you pass --output-dir:
plan-report-20260602T120000Z.htmlpreflight-report-20260602T120000Z.json
The log format is chosen once per run with log_format: text for a readable transcript, html for the styled report, json for a machine-readable document. Passing an explicit log_file with a directory in it overrides the naming convention and the directory both. See Configuration.
Human-facing and machine-facing
The same run can produce both. An HTML report goes to the approver; a JSON or SARIF file goes to the pipeline. The JSON log is a complete document rather than a stream of lines, and it declares its own version so a parser can tell what it is looking at.
{
"log_format_version": "1.0",
"dblift_version": "…"
}On the command line, five output formats are a parser-facing contract with stdout kept clean of banners and log lines: json, sarif, github-actions, gitlab, compact. See Exit Codes.
Retention
DBLift does not delete artifacts on your behalf, with one exception: snapshots are capped by max_snapshots, which defaults to 1. Raise it if an approver needs to compare a release against more than the previous state.
| Keep | The plan and preflight reports for the release, and the migration report from the apply. |
| Attach | SARIF to the pull request that introduced the SQL, where the finding sits beside the line. |
| Never edit | The history table. Use repair so the correction is itself recorded. |
Check it in print view once
Reports invert to white under print, so a PDF filed with a change ticket looks the same as the page an approver reviewed. Anything you intend to keep as evidence should survive that inversion.