DATABASE INFRASTRUCTURE
DBWarden
Declarative schema compiler that derives deterministic database migrations from SQLAlchemy models.
Your models are the source code. SQL is the output.
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. Most tools ask you to maintain two representations of your schema: ORM models and migration files. When they diverge, you find out at deploy time. Making this deterministic requires: a diff engine that handles renames, type changes, constraint changes, and ordering across 5 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.
Workflow
Point at existing models
dbwarden reads your SQLAlchemy models as the single source of truth.
make-migrations
Generates a baseline schema or diffs against the current database state.
Commit generated SQL
Plain SQL files: reviewable, committable, executable anywhere.
migrate
Applies pending migrations with convergence verification.
Optional: impact analysis, offline mode, plugins
AST-based breaking change detection, CI without a database, seeds/RBAC/FastAPI integration.
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
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
8 official plugins for seeds, RBAC, FastAPI, sandbox testing, and PostgreSQL/ClickHouse extensions.
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.
Ecosystem
wlite
CLI + bindingsDeclarative SQLite schema management without the Python overhead. Same philosophy as dbwarden, stripped to what SQLite and C can do alone.
GitHub ↗libwlite
C librarydbwarden's SQLite3 engine extracted as a standalone C library. Parses .wlite model files, manages SQLite databases, compares schemas, generates migrations. The core runtime for wlite.
GitHub ↗dbwarden-harness
Test suiteStandalone black-box validation suite. PyPI installation checks, CLI contract checks, real migration application across all 5 DB providers, rollback/recovery, and plugin discovery.
GitHub ↗Results
Tradeoffs
- ·Requires SQLAlchemy 2.0+ (not compatible with legacy models)
- ·Schema compilation adds a build step vs. runtime migration
- ·Declarative approach means less control over migration ordering