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() -> strThe psycopg conninfo projection — consumers never hand-build it (make_conninfo quotes and escapes, so exotic passwords survive).
from_env
@classmethoddef from_env(prefix: str = 'POSTGRES', env: dict[str, str] | None = None) -> DBConnectionConfigPOSTGRES_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).")