/ correctness

Compilation
Correctness.

dbwarden compiles models to SQL. These are the guarantees that make the compilation trustworthy: deterministic output, verified rollback, convergence against real databases, and offline integrity.

/ 01 Deterministic diffsRead the docs ↗

Same inputs, same SQL, every time.

After every migration, dbwarden writes a checksummed JSON snapshot of the schema to .dbwarden/schemas/. Generation diffs models against that snapshot or live state, so the same inputs produce the same SQL on every machine. Renames come out as renames, not as a drop plus a create.

/ 02 Rollback contractRead the docs ↗

Rollback is classified before it ships.

Every generated migration carries upgrade and rollback sections, and dbwarden classifies the rollback before the file is accepted: real, conditional, irreversible, or placeholder. Placeholder rollback is refused by default. When a change cannot be reversed (an enum value addition, a lossy ClickHouse engine swap), the migration has to declare it explicitly.

-- upgrade
ALTER TABLE users ADD COLUMN bio TEXT;

-- rollback
ALTER TABLE users DROP COLUMN bio;

For the rare truly irreversible change:

-- dbwarden: irreversible

/ 03 Convergence gateRead the docs ↗

Full history, replayed from scratch.

CI starts an empty database, applies every migration exactly as production would, extracts the resulting schema, and compares it with the models. Any drift fails the build. After a Git merge, resolve MERGE_PENDING with dbwarden merge before rerunning the gate.

$ dbwarden migrate --database primary
$ dbwarden diff --database primary   # must report zero differences

This catches what syntax checks miss: a migration that forgot the model's index, a column removed from the model but never dropped, a rename applied backwards, backend metadata missing from hand-written SQL. On long histories, migrate --defer-snapshots replays hundreds of migrations with a single final snapshot instead of one reflection per file.

/ 04 Round-trip verificationRead the docs ↗

Upgrade and rollback, exercised in sequence.

A test harness applies a migration and its rollback in sequence and verifies the schema returns to its starting state. The rollback path actually runs, rather than existing only as generated text.

/ 05 Offline integrityRead the docs ↗

Generate without a database. Verify against one.

export-models commits a checksummed model state file; make-migrations --offline diffs against it with no database service in CI. Offline generation is deterministic, and the convergence gate on a live database proves the SQL actually applies.

$ dbwarden export-models --database primary
$ dbwarden make-migrations "add bio" --offline

/ honest limits

What it verifies

Schema shape, rollback executability, and that the full migration history reproduces the models.

What it can't

Business intent. An ERROR classification is a review boundary, not a guarantee; deleted data stays deleted.