Database Configuration

URL-Based Configuration

Django-CFG uses URL-based configuration for databases, providing a simple, consistent interface across all database backends (PostgreSQL, MySQL, SQLite, etc.).

Quick Start

Environment Variables

.env

DATABASE__URL="postgresql://user:password@localhost:5432/mydb"

api/environment/loader.py

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict

class DatabaseConfig(BaseSettings):
    url: str = Field(default="sqlite:///db/default.sqlite3")

    model_config = SettingsConfigDict(
        env_prefix="DATABASE__",
        env_nested_delimiter="__",
    )

env = EnvironmentConfig()  # Auto-loads from ENV and .env

api/config.py

from django_cfg import DjangoConfig, DatabaseConfig
from .environment import env

class MyConfig(DjangoConfig):
    databases = {
        "default": DatabaseConfig.from_url(url=env.database.url)
    }

config = MyConfig()

Production Secrets

Always use environment variables for database credentials in production. Never commit passwords to version control.

Direct Config

api/config.py

from django_cfg import DjangoConfig, DatabaseConfig

class MyConfig(DjangoConfig):
    databases: dict[str, DatabaseConfig] = {
        "default": DatabaseConfig.from_url(
            url="postgresql://user:password@localhost:5432/mydb"
        )
    }

config = MyConfig()

Not Recommended

Hardcoded credentials are a security risk. Use environment variables instead.

Automatic Conversion

Django-CFG automatically converts database.url to Django's DATABASES setting using dj-database-url. No manual dictionary configuration needed.

Database URL Formats

URL Pattern

All database URLs follow the pattern: backend://user:password@host:port/database?options

PostgreSQL

PostgreSQL URL Examples

# Basic connection
url = "postgresql://user:password@localhost:5432/dbname"

# Default port (5432 can be omitted)
url = "postgresql://user:password@localhost/dbname"

# Short form (postgres:// also works)
url = "postgres://user:password@localhost/dbname"

# With SSL (production)
url = "postgresql://user:password@localhost/dbname?sslmode=require"

# Connection timeout
url = "postgresql://user:password@localhost/dbname?connect_timeout=10"

# Multiple options
url = "postgresql://user:password@localhost/dbname?sslmode=require&connect_timeout=10"

PostgreSQL in Production

PostgreSQL is the recommended database for production Django applications due to:

• Advanced features (JSON fields, full-text search, arrays)
• Excellent Django ORM support
• Strong data integrity and ACID compliance
• Active development and community support

MySQL/MariaDB

MySQL URL Examples

# Basic MySQL connection
url = "mysql://user:password@localhost:3306/dbname"

# MariaDB (same format)
url = "mysql://user:password@localhost:3306/dbname"

# With charset
url = "mysql://user:password@localhost/dbname?charset=utf8mb4"

# Connection options
url = "mysql://user:password@localhost/dbname?init_command=SET sql_mode='STRICT_TRANS_TABLES'"

# SSL connection
url = "mysql://user:password@localhost/dbname?ssl_ca=/path/to/ca.pem"

MySQL Charset

Always use charset=utf8mb4 for full Unicode support (including emojis). The default utf8 is limited to 3-byte UTF-8 characters.

SQLite

SQLite URL Examples

# File-based database (development)
url = "sqlite:///db/mydb.sqlite3"

# Relative path
url = "sqlite:///./mydb.sqlite3"

# Absolute path
url = "sqlite:////absolute/path/to/mydb.sqlite3"

# In-memory database (testing)
url = "sqlite:///:memory:"

SQLite Use Cases

SQLite is ideal for:

• Development: Quick setup, no server needed
• Testing: In-memory databases for fast tests
• Small deployments: Single-server applications with light load

NOT recommended for production with multiple workers or high concurrency.

Other Databases

Other Database Backends

# Oracle
url = "oracle://user:password@localhost:1521/dbname"

# Microsoft SQL Server
url = "mssql://user:password@localhost:1433/dbname"

# CockroachDB (PostgreSQL-compatible)
url = "cockroachdb://user:password@localhost:26257/dbname?sslmode=require"

# Amazon Redshift (PostgreSQL-compatible)
url = "redshift://user:password@cluster.region.redshift.amazonaws.com:5439/dbname"

Custom Backends

For databases not listed here, ensure the appropriate Django database backend is installed and use the correct URL scheme.

Advanced URL Options

Connection Pooling

# PgBouncer connection pooling
url = "postgresql://user:password@pgbouncer:6432/dbname?sslmode=require"

# Django connection pool settings (via DatabaseConfig)
databases: dict[str, DatabaseConfig] = {
    "default": DatabaseConfig.from_url(
        url=env.database.url,
        options={
            "MAX_CONNS": 20,
            "MIN_CONNS": 5,
        }
    )
}

SSL/TLS Configuration

# PostgreSQL SSL modes
url = "postgresql://user:pass@host/db?sslmode=disable"   # No SSL
url = "postgresql://user:pass@host/db?sslmode=allow"     # Try SSL, fallback to plain
url = "postgresql://user:pass@host/db?sslmode=prefer"    # Prefer SSL
url = "postgresql://user:pass@host/db?sslmode=require"   # Require SSL (production)
url = "postgresql://user:pass@host/db?sslmode=verify-ca" # Verify CA certificate
url = "postgresql://user:pass@host/db?sslmode=verify-full" # Full verification

Timeout Configuration

# Connection timeout (seconds)
url = "postgresql://user:pass@host/db?connect_timeout=10"

# Statement timeout (milliseconds)
url = "postgresql://user:pass@host/db?options=-c statement_timeout=30000"

Topics

• URL Configuration - URL-based database setup
• Multi-Database - Multiple database configuration
• Routing - Database routing system
• Migrations - Migration commands
• Cross-Database Relations - ForeignKeys across databases

See Also

• Multi-Database Guide - Complete multi-database setup
• Configuration Guide - DjangoConfig models
• Environment Variables - Configure via YAML/env