Configuration System

Location: config/

Manages application settings from multiple sources.

Configuration Structure

python

@dataclass
class DbliftConfig:
    database: DatabaseConfig
    migrations: MigrationsConfig
    history_table: str = "dblift_schema_history"
    snapshot_table: str = "dblift_schema_snapshots"
    max_snapshots: int = 1
    log_level: str = "INFO"
    log_file: Optional[str] = None
    log_format: str = "text"

@dataclass
class DatabaseConfig:
    url: str                    # SQLAlchemy URL or connection string
    username: Optional[str]
    password: Optional[str]
    schema: str
    type: str                   # postgresql, mysql, sqlserver, oracle, db2, sqlite, duckdb, cosmosdb

@dataclass
class MigrationsConfig:
    directory: Optional[str]           # Single directory
    directories: List[DirectoryConfig] # Multiple directories
    script_encoding: str = "utf-8"
    detect_encoding: bool = False
    recursive: bool = False           # Global recursive default

Configuration Loading

Precedence (highest to lowest):

CLI arguments (--db-url, --db-schema, etc.)
Environment variables (DBLIFT_DB_URL, DBLIFT_DB_SCHEMA, etc.)
YAML configuration file
Default values

Property registry (surface parity)

config/property_registry.py holds a single PropertySpec registry that is the source of truth for every persistent property's three surfaces. Each spec mechanically derives its environment variable (DBLIFT_FOO_BAR) and CLI flag (--foo-bar) from its config key (foo_bar), and from_env_dict, from_args_dict, and the CLI-flag generator (cli/_parser_setup._add_registry_flags) all read from it. This keeps the surfaces in lock-step — a property added to the registry is reachable everywhere — instead of relying on several hand-maintained lists that could drift apart. PropertySpec.cli_only marks runtime-only flags (e.g. --version), cli_exempt marks options that are config/env only (e.g. retry tuning), and cli_aliases records legacy flag names (e.g. --table for history_table). dblift config --list renders the registry at runtime. The tests/unit/config/test_property_parity*.py invariants fail if any surface drifts.

Example:

python

from dblift.config.config_builder import ConfigBuilder

# Load from file with overrides
config = ConfigBuilder.build(
    file_path="dblift.yaml",
    env_overrides=True,
    database_url="postgresql+psycopg://localhost/testdb",  # CLI override
    database_schema="test_schema"
)

YAML Configuration Example

yaml

# dblift.yaml
database:
  url: "postgresql+psycopg://localhost:5432/mydb"
  username: "myuser"
  password: "mypass"
  schema: "public"

migrations:
  directories:
    - path: "./migrations/core"
      recursive: true
    - path: "./migrations/features"
      recursive: false
  script_encoding: "utf-8"
  detect_encoding: false

history_table: "dblift_schema_history"
snapshot_table: "dblift_schema_snapshots"
max_snapshots: 3

logging:
  level: "INFO"
  format: "text"

Environment Variables

All configuration options can be overridden via environment variables:

# Database configuration
export DBLIFT_DB_URL="postgresql+psycopg://localhost:5432/mydb"
export DBLIFT_DB_USERNAME="myuser"
export DBLIFT_DB_PASSWORD="mypassword"
export DBLIFT_DB_SCHEMA="public"
export DBLIFT_DB_TYPE="postgresql"
 
# Migration configuration
export DBLIFT_MIGRATIONS_DIRECTORY="./migrations"
export DBLIFT_MIGRATIONS_SCRIPT_ENCODING="utf-8"
 
# History and snapshots
export DBLIFT_HISTORY_TABLE="dblift_schema_history"
export DBLIFT_SNAPSHOT_TABLE="dblift_schema_snapshots"
export DBLIFT_MAX_SNAPSHOTS="5"
 
# Logging
export DBLIFT_LOG_LEVEL="DEBUG"
export DBLIFT_LOG_FORMAT="json"

Database-Specific Configuration

SQLite

yaml

database:
  type: "sqlite"
  path: "/path/to/database.db"  # Or ":memory:" for in-memory
  schema: "main"

DuckDB

yaml

database:
  type: "duckdb"
  path: "/path/to/database.duckdb"
  schema: "main"

CosmosDB

yaml

database:
  type: "cosmosdb"
  account_endpoint: "https://your-account.documents.azure.com:443/"
  account_key: "your-account-key"
  database_name: "your-database"
  # Or use managed identity:
  # use_managed_identity: true

Validation

Configuration is validated on load:

Database connection parameters are checked
Migration directories are verified to exist
Database type is validated
Required fields are present

Use dblift db validate-config to check configuration without connecting.

User Guide Configuration - User-facing configuration guide
Architecture Overview - How configuration is used

PreviousEvents & callbacks NextExit codes

Configuration System

Configuration Structure

Configuration Loading

Property registry (surface parity)

YAML Configuration Example

Environment Variables

Database-Specific Configuration

SQLite

DuckDB

CosmosDB

Validation

Related Documentation