Configuration¶

DBWarden uses Python-based configuration with database_config() to define your databases.

One configuration source for migrations, CLI tools, and runtime: no split configs.

Quick Start¶

The simplest configuration possible:

# dbwarden.py
from dbwarden import database_config

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

That's it! 4 parameters to get started.

Run your first migration:

$ dbwarden init
$ dbwarden make-migrations "initial schema"
$ dbwarden migrate

Learning Path¶

New to DBWarden?¶

Start here to understand configuration basics:

Quick Start - Your first configuration in 2 minutes
Concepts - How configuration works
Connection URLs - Database connection formats

Building Your Configuration¶

Learn specific features:

Model Discovery - How DBWarden finds your SQLAlchemy models
Dev Mode - Local development with SQLite
Multi-Database - Configure multiple databases

Production Ready¶

Deploy with confidence:

Production Patterns - Real-world examples
Troubleshooting - Common issues and solutions

Complete Reference¶

Configuration API - Complete function signature and parameters

Key Features¶

Simple Configuration¶

Define once, use everywhere:

primary = database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url_sync="postgresql://localhost/myapp",
    model_paths=["app.models"],
)

Dev Mode¶

Use SQLite locally, PostgreSQL in production:

primary = database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url_sync="postgresql://localhost/myapp",
    dev_database_type="sqlite",
    dev_database_url="sqlite:///./dev.db",
)

Run commands with --dev:

$ dbwarden --dev migrate
$ dbwarden --dev status

Multi-Database¶

Configure as many databases as you need:

# Primary database
primary = database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url_sync="postgresql://localhost/main",
    model_paths=["app.models.primary"],
)

# Analytics database
analytics = database_config(
    database_name="analytics",
    database_type="clickhouse",
    database_url_sync="http://localhost:8123/analytics",
    model_paths=["app.models.analytics"],
)

Security First¶

Keep credentials out of code:

import os

primary = database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url_sync=os.getenv("DATABASE_URL"),
    secure_values=True,  # Hide credentials in output
)

Validation¶

DBWarden validates your configuration:

Exactly one default=True
Unique database names
No duplicate URLs
Required model_paths for multi-database
Consistent dev mode configuration

Configuration Loading¶

DBWarden discovers your configuration automatically:

Looks for dbwarden.py in current directory or parents
Checks DBWARDEN_CONFIG_MODULE environment variable
Scans for database_config() calls in your codebase (full project tree walk)
Looks for warden.toml as an alternative TOML-based config file

dbwarden.py is the default convention and the file created by dbwarden init, but database_config(...) can live in any discovered Python file inside your project.

Common Patterns¶

Single Database (Minimal)¶

from dbwarden import database_config

primary = database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url_sync="postgresql://localhost/myapp",
)

With Dev Mode (Recommended)¶

from dbwarden import database_config

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

Multiple Databases¶

from dbwarden import database_config

# Primary
primary = database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url_sync="postgresql://localhost/main",
    model_paths=["app.models.primary"],
)

# Analytics
analytics = database_config(
    database_name="analytics",
    database_type="postgresql",
    database_url_sync="postgresql://localhost/analytics",
    model_paths=["app.models.analytics"],
)

Production with Environment Variables¶

import os
from dbwarden import database_config

primary = database_config(
    database_name="primary",
    default=True,
    database_type="postgresql",
    database_url_sync=os.getenv("DATABASE_URL"),
    model_paths=["app.models"],
    secure_values=True,
)

Why Python Configuration?¶

vs TOML/YAML/INI: - Type checking with your IDE - Dynamic configuration (loops, conditionals) - Environment variable integration - No schema mismatches - Can compute values

vs Environment Variables Only: - Version controlled - Self-documenting - Validation at load time - Multiple databases easy - Can reference code structures

What's Next?¶

Ready to configure your first database? Start here:

Quick Start - Build your first configuration
Concepts - Understand how it works
Production Patterns - Real-world examples

Already familiar with configuration? Jump to:

Connection URLs - URL format reference
Troubleshooting - Common issues
Configuration API - Complete reference