Skip to content

common_db.schemas.configs

configs.py — the suite’s operating instructions: the connection, the pool, and every op’s knobs.

Defaults law: every field defaulted; a consumer adjusts ANY subset and the rest hold. merge(**overrides) returns a NEW config — None means leave-unchanged, never “set to nothing”. Secrets are masked at every repr.

Classes

DBConnectionConfig

Bases: _Config

Who/where — one Postgres target (tailnet addresses are the reality; multi-target routing = several of these, keyed by name in the client).

Fields and properties declared here; inherited members belong to the bases above.

connect_timeout

connect_timeout: float = Field(default=10.0, gt=0, description='Seconds to wait for a connection.')

database

database: str = Field(default='postgres', min_length=1, description='Database name.')

host

host: str = Field(default='localhost', min_length=1, description='Server host (tailnet address in our world).')

password

password: SecretStr = Field(default=(SecretStr('')), description='Role password (masked everywhere).')

port

port: int = Field(default=5432, ge=1, le=65535, description='Server port.')

sslmode

sslmode: str | None = Field(default=None, description='libpq sslmode, when needed.')

statement_timeout_ms

statement_timeout_ms: int | None = Field(default=None, ge=0, description='Server-side statement timeout for THIS target (the monitoring plane runs 5000ms so audit writes can never wedge a job — per-target posture).')

type

type: Literal['postgres'] = Field(default='postgres', description='The backend; PostgreSQL is the one today.')

user

user: str = Field(default='postgres', min_length=1, description='Role name.')

conninfo

def conninfo() -> str

The psycopg conninfo projection — consumers never hand-build it (make_conninfo quotes and escapes, so exotic passwords survive).

from_env

@classmethod
def from_env(prefix: str = 'POSTGRES', env: dict[str, str] | None = None) -> DBConnectionConfig

POSTGRES_HOST/PORT/DB/USER/PASSWORD (the established names).

PoolConfig

Bases: _Config

Connection-pool posture (psycopg_pool). The legacy monitoring plane proved per-target posture matters: pre-ping + recycle kept audit writes alive across pod restarts.

Fields and properties declared here; inherited members belong to the bases above.

check_on_checkout

check_on_checkout: bool = Field(default=True, description='Liveness-check connections at checkout (the pre_ping lesson).')

max_idle

max_idle: float = Field(default=600.0, ge=0, description='Seconds an idle connection may live.')

max_lifetime

max_lifetime: float = Field(default=3600.0, gt=0, description='Seconds before a connection is recycled outright.')

max_size

max_size: int = Field(default=8, gt=0, description='Hard pool ceiling.')

min_size

min_size: int = Field(default=1, ge=0, description='Connections kept warm.')

timeout

timeout: float = Field(default=30.0, gt=0, description='Seconds to wait for a free connection.')

ReadConfig

Bases: _Config

How reads come back — total output control.

Fields and properties declared here; inherited members belong to the bases above.

batch_rows

batch_rows: int = Field(default=100000, gt=0, description='Fetch batch size for row streams.')

dtypes

dtypes: dict[str, str] = Field(default_factory=dict, description='Per-column dtype overrides.')

index

index: tuple[str, ...] = Field(default=(), description='Columns to set as index (pandas output).')

output

output: OutputKind = Field(default=(OutputKind.POLARS), description='Result container.')

WriteConfig

Bases: _Config

How writes behave — the op knobs with the suite’s safe defaults.

Fields and properties declared here; inherited members belong to the bases above.

batch_rows

batch_rows: int = Field(default=50000, gt=0, description='COPY flush granularity.')

coerce

coerce: CoercePolicy = Field(default=(CoercePolicy.COERCE), description='Dtype-drift posture.')

create_missing

create_missing: bool = Field(default=True, description='Create the table (inferred from the data) when absent.')

evolve

evolve: bool = Field(default=False, description='Allow dynamic ADD COLUMN for new incoming columns.')

on_missing

on_missing: ReconcilePolicy = Field(default=(ReconcilePolicy.ARCHIVE), description="Reconcile's stale-row policy (never destructive by default).")

stale_cap

stale_cap: int = Field(default=100, ge=0, description="Reconcile's mass-removal tripwire (the data-updater MAX_AUTO_HEAL lesson): more stale rows than this REFUSES and reports instead of acting. 0 disables the cap — an explicit, mergeable opt-in (None would collide with merge's leave-unchanged law).")