DB backends
5
CLI commands
14
Official plugins
7
Release harness
FULL
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.
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.
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
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
The compiler is the centre of a set of independently versioned tools.
wlite
CLI + bindingsDeclarative SQLite schema management without the Python overhead. The same philosophy as DBWarden, stripped to what SQLite and C can do alone.
libwlite
C libraryDBWarden's SQLite engine extracted as a standalone C library. Parses .wlite model files, manages databases, compares schemas, and generates migrations.
dbwarden-harness
Release certificationStandalone black-box validation across five real databases: PyPI install, CLI contract, migration application, rollback, and plugin discovery.
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