Installation¶

This guide covers installing dbwarden in your project and verifying it works correctly.

Requirements¶

• Python 3.10 or higher
• A project that uses SQLAlchemy for database models
• uv or another Python package manager

Install using uv¶

uv add dbwarden

Development dependencies¶

To also install testing and linting tools:

uv add "dbwarden[dev]"

Optional dependency groups¶

The [postgres] extra is the most commonly used. Install it if you are targeting PostgreSQL.

Combine groups as needed:

uv add "dbwarden[postgres,mysql,fastapi]"

Database drivers¶

dbwarden uses SQLAlchemy under the hood. The recommended way to install drivers is via the extras above:

# PostgreSQL
uv add "dbwarden[postgres]"

# MySQL/MariaDB
uv add "dbwarden[mysql]"

# ClickHouse
uv add "dbwarden[clickhouse]"

# SQLite comes bundled with Python

You can also install drivers directly if you prefer:

uv add psycopg2-binary    # PostgreSQL
uv add pymysql            # MySQL / MariaDB
uv add clickhouse-connect # ClickHouse

Verify installation¶

After installing, confirm dbwarden is available:

$ dbwarden version

You should see output:

0.9.4

Initialize in your project¶

Create the dbwarden structure in your project directory:

$ dbwarden init

This creates:

• a migrations/ directory structure
• a dbwarden.py config scaffold (or discovers your existing config source)

What happens during init¶

When you run init, dbwarden:

1. Creates migrations/ if missing
2. Creates dbwarden.py (or updates existing config source) with declarative class scaffolding
3. Does not overwrite existing database_config(...) definitions you have added

You can run init safely on an existing project - it is idempotent.

Quick configuration¶

After init, configure your first database by editing dbwarden.py (or your existing config file):

from dbwarden import DbwardenDatabase


class Primary(DbwardenDatabase):
    database_name = "primary"
    default = True
    database_type = "postgresql"
    database_url_sync = "postgresql://user:password@localhost:5432/mydb"
    dev_database_type = "sqlite"
    dev_database_url = "sqlite:///./development.db"

The dev_database_* fields are optional but recommended - they enable fast local iterations with --dev. The function alternative, database_config(...), remains supported, and some plugins use it in examples or integration code.

Verify configuration loads¶

$ dbwarden settings show --all

You should see your database entry printed with type and URL.

Common installation issues¶

Command not found after uv add

• Ensure your virtual environment is activated
• Try removing and re-adding: uv remove dbwarden && uv add dbwarden

Import errors or missing module warnings

• Upgrade uv and reinstall: uv add --upgrade dbwarden

Database driver errors

• Install the appropriate driver for your target database (see Database drivers section above)

Upgrading¶

To update to a newer version:

uv add --upgrade dbwarden

Or with poetry:

poetry update dbwarden

Check the release notes when upgrading major versions - there may be configuration or workflow changes.