Skip to content

Quick Start

Configure your first database in 2 minutes.

Prerequisites

You should have: - Python 3.10+ installed - DBWarden installed (pip install dbwarden) - A database to connect to (or use SQLite)

Step 1: Initialize

Create project structure:

dbwarden init

This creates: - migrations/ directory - dbwarden.py configuration file

Step 2: Your First Configuration

Open dbwarden.py and add:

from dbwarden import database_config

database_config(
    database_name="primary",
    default=True,
    database_type="sqlite",
    database_url="sqlite:///./app.db",
)

That's it! 4 required parameters: - database_name - What to call this database - default - Is this the default? - database_type - What kind of database? - database_url - How to connect?

Use SQLite First

Start with SQLite for the simplest setup. Switch to PostgreSQL later.

Step 3: Test the Configuration

Verify DBWarden can read your config:

dbwarden database

You'll see:

Database Configuration
════════════════════════════════════════

primary (default)
  Type: sqlite
  URL: sqlite:///./app.db
  Migrations: migrations/primary

Step 4: Add Model Paths (Optional)

If you have SQLAlchemy models, tell DBWarden where they are:

database_config(
    database_name="primary",
    default=True,
    database_type="sqlite",
    database_url="sqlite:///./app.db",
    model_paths=["app.models"],  # ← Add this
)

DBWarden will discover models from app.models and its submodules.

Step 5: Upgrade to PostgreSQL

When you're ready for PostgreSQL:

database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url="postgresql://user:password@localhost:5432/myapp",
    model_paths=["app.models"],
)

Keep SQLite for local dev, use PostgreSQL in production:

database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url="postgresql://user:password@localhost:5432/myapp",
    dev_database_type="sqlite",
    dev_database_url="sqlite:///./dev.db",
    model_paths=["app.models"],
)

Now you can run commands against SQLite locally:

dbwarden --dev migrate
dbwarden --dev status

And against PostgreSQL in production:

dbwarden migrate
dbwarden status

What Just Happened?

database_config() Registered Your Database

When Python loads dbwarden.py, it executes database_config() which: 1. Validates your parameters 2. Registers the database in DBWarden's internal registry 3. Sets up migration directories

DBWarden Can Now Find Your Database

All CLI commands now know about your database:

dbwarden make-migrations "create users"
dbwarden migrate
dbwarden status
dbwarden history

Common First-Time Issues

"No configuration found"

Cause: DBWarden can't find dbwarden.py

Solution: Ensure you're in the project directory and dbwarden.py exists.

"No SQLAlchemy models found"

Cause: DBWarden can't discover your models

Solution: Add model_paths to your config:

model_paths=["app.models"]

"Exactly one default=True required"

Cause: Multiple databases without one marked as default

Solution: Set one database to default=True

Complete Minimal Example

# dbwarden.py
from dbwarden import database_config

database_config(
    database_name="primary",
    default=True,
    database_type="sqlite",
    database_url="sqlite:///./app.db",
    model_paths=["app.models"],
)

Complete Production Example

# dbwarden.py
import os
from dbwarden import database_config

database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url=os.getenv("DATABASE_URL"),
    dev_database_type="sqlite",
    dev_database_url="sqlite:///./dev.db",
    model_paths=["app.models"],
    secure_values=True,
)

Recap

You learned how to:

✅ Initialize a DBWarden project
✅ Create your first database_config()
✅ Verify configuration with dbwarden database
✅ Add model discovery
✅ Upgrade from SQLite to PostgreSQL
✅ Add dev mode for local development
✅ Use environment variables for credentials

What's Next?