Skip to content

Commands Overview

DBWarden commands are organized by workflow: setup, generation, execution, inspection, and operations.

Global Flags

Flag What it does
--dev Use dev_database_url / dev_database_type for the selected database
--strict-translation In dev SQLite flows, fail instead of fallback on lossy SQL translation
-h, --help Show command help

Command Groups

Setup

Command Purpose
init Initialize warden.toml and migration folder structure
database Add/list/remove configured databases

Migration Authoring

Command Purpose
make-migrations Generate SQL from SQLAlchemy models
new Create manual migration template
squash Merge consecutive migrations

Migration Execution

Command Purpose
migrate Apply pending migrations
rollback Roll back applied migrations

Inspection and Diagnostics

Command Purpose
status Show applied/pending migration state
history Show execution history
check-db Inspect live database schema
diff Compare models vs current schema

Lock Operations

Command Purpose
lock-status Inspect migration lock state
unlock Clear lock in recovery scenarios 
# 1) Generate migration
dbwarden make-migrations "add billing tables" -d primary

# 2) Review generated SQL file

# 3) Apply migration locally
dbwarden --dev migrate -d primary

# 4) Validate state
dbwarden status -d primary

Multi-Database Execution Patterns

Single database:

dbwarden migrate -d primary

All databases in sequence:

dbwarden migrate --all

Dev mode on selected database:

dbwarden --dev migrate -d analytics

How Execution Commands Work Internally

For migrate and rollback, DBWarden follows this algorithm:

def execute_migration_operation(target_db):
    ensure_metadata_tables_exist(target_db)
    acquire_lock(target_db)
    try:
        plan = build_execution_plan(target_db)
        for step in plan:
            run_sql(step.statements)
            record_migration_event(step)
    finally:
        release_lock(target_db)

The lock guarantees only one migration process mutates a given database at a time.

See Also