01Database infrastructure

DBWarden

Declarative schema compiler that derives deterministic database migrations from SQLAlchemy models.

Your models are the source code. SQL is the output.

Python 3.12+SQLAlchemy 2.0PostgreSQLMySQLMariaDBSQLiteClickHouse

GitHub Docs PyPI Harness

Latest repository commit

Loading latest commits…

DB backends

Official plugins

Test files

166

Release

v0.20.10

Problem

Schema management tools fall into two camps. Imperative tools have you author changes: revision scripts that describe how to get from one schema version to the next. Declarative tools have you author the desired state and derive the changes for you. Most imperative tools ask you to maintain two representations of your schema: your ORM models and your migration files. When they drift, you find out at deploy time.

Why it's hard

Schema drift is the core enemy. Making this deterministic requires a diff engine that handles renames, type changes, constraint changes, and ordering across five database backends with different DDL dialects. Every migration must carry both upgrade and rollback SQL, and the rollback must be tested against the actual database.

Capabilities

Impact analysis

dbwarden check-impact scans the codebase with AST analysis and a grep fallback, then reports every reference to a column or table a migration changes before deploy.

Offline generation

Export model state once, then generate migrations in CI or on a machine with no database using make-migrations --offline.

Schema snapshots

Every migration writes a checksummed JSON snapshot. Snapshots power rename detection, offline diffs and column-level comparisons.

Typed Meta

A metaclass validates every class Meta attribute at import time; typos that would produce wrong DDL raise DBWardenConfigError immediately.

Reverse engineering

Generate SQLAlchemy models from a live database with generate-models, including backend metadata and a custom --base import.

Multi-database

One project can target several databases with isolated configs, per-database table ownership and optional databases that skip when missing.

Workflow

01
Point at existing models
DBWarden reads your SQLAlchemy models as the single source of truth.
02
make-migrations
Generates a baseline schema or diffs against the current database state.
03
Commit generated SQL
Plain SQL files: reviewable, committable, executable anywhere.
04
migrate
Applies pending migrations with convergence verification.
05
Optional: impact analysis, offline mode, plugins
AST-based breaking change detection, CI without a database, seeds/RBAC/FastAPI integration.

Key decisions

SQL-first output

Migrations are plain SQL files. No runtime, no generated Python. Reviewable, committable, executable anywhere.

Deterministic diff

Same models + same snapshot = same migration. Always. No hidden state, no ordering dependencies.

Strict rollback contract

Every migration carries upgrade + rollback SQL. Placeholder rollback refused by default.

Plugin architecture

7 official plugins for seeds, RBAC, FastAPI, sandbox testing, and PostgreSQL/ClickHouse extensions.

Safety model

Migration generation classifies every operation, splits type changes into expand-contract steps, and assigns severity. The CLI adds execution ceilings, pending-plan checks and structured impact reports, so a destructive change can be stopped before it reaches production.

History stays auditable: checksummed snapshots, repeatable migrations, merge reconciliation and rebase support. Rollbacks are generated where safe; irreversible changes require an explicit declaration instead of a placeholder.

Constraints

No migration runtime to install or version
No generated Python scripts that quietly do the wrong thing
No schema drift discovered in production
Migrations that can be generated in CI without a database connection

Supported databases

Supported databases
Database	Round-trip	Notes
PostgreSQL	Full	Identity and generated columns, partitioning, inheritance, exclusion constraints, enum types and advanced indexes.
MySQL	Full	DDL parity, engine/charset/collation options, unsigned and on-update columns.
ClickHouse	Full	MergeTree family, replicated engines, projections, dictionaries, materialized views and skip indexes.
SQLite	Full	WITHOUT ROWID/STRICT, generated columns, table rebuilds for unsupported ALTERs.
MariaDB	Partial	Schema layer complete; snapshot and reverse-engineering gaps remain.

Round-trip means model → SQL → live database → model validation.

Status

Stable Alpha: pre-1.0 but production-ready. No breaking change ships without a 3-month deprecation window.

Test harness

dbwarden Test Harness is a standalone black-box validation suite. It installs DBWarden as a consumer, invokes its public CLI, creates disposable real database instances via Testcontainers, and verifies the compiled SQL produces the correct schema. This is not a unit test suite; it is a release certification boundary.

Harness coverage

PyPI installationPASS

CLI contractPASS

5 DB providersPASS

Migration applicationPASS

Constraint enforcementPASS

Regeneration silencePASS

Rollback / recoveryPASS

Plugin discoveryPASS

Ecosystem

The compiler is the centre of a set of independently versioned tools.

wlite

CLI + bindings

Declarative SQLite schema management without the Python overhead. The same philosophy as DBWarden, stripped to what SQLite and C can do alone.

C++RustPythonGoC#Zig

Source ↗

libwlite

C library

DBWarden's SQLite engine extracted as a standalone C library. Parses .wlite model files, manages databases, compares schemas, and generates migrations.

C11SQLite3

Source ↗