Skip to content

common_db.client.base

base.py — BaseDBClient: connections, targets, transactions, lifecycle.

Owns the algebra every backend shares: pooled connections (psycopg_pool), a sync pool and an async pool per target — the sync one carries the op engine (COPY, staging, one transaction per op), the async one carries a consumer’s own short transactions from an event loop (aconnection / atx) — MULTI-TARGET routing (the three-plane lesson: prices/configs/monitoring run different postures — each target is a named DBConnectionConfig + PoolConfig), transaction scopes, and the four context dunders. Ops live in the concrete client (pg.py); this class never writes a row.

Connection is CONFIG, never code: plain psycopg3 to the address in the config (tailnet addresses in our world). No tunnels, no shelling out — by ruling.

Classes

BaseDBClient

Pooled, multi-target, transaction-scoped — the connection engine.

__init__

def __init__(connection: DBConnectionConfig | dict[str, Any] | None = None, *, targets: dict[str, DBConnectionConfig | dict[str, Any]] | None = None, pool: PoolConfig | dict[str, Any] | None = None, default_target: str = 'default') -> None

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

active_target

Read-only property.

active_target: str

is_open

Read-only property.

is_open: bool

max_pool_size

Read-only property.

max_pool_size: int

Maximum connections available to one named target pool.

targets

Read-only property.

targets: tuple[str, ...]

aclose

async def aclose() -> None

Close every pool, the async ones awaited on this loop.

aconnection

async def aconnection(target: str | None = None) -> AsyncIterator[psycopg.AsyncConnection]

One pooled ASYNC connection, returned on exit — for a consumer’s own short transactions from an event loop; the op engine stays on the sync pool.

aping

async def aping(target: str | None = None) -> bool

Liveness through the async pool — SELECT 1.

atx

async def atx(target: str | None = None) -> AsyncIterator[psycopg.AsyncConnection]

One explicit ASYNC transaction scope: everything inside commits together or not at all.

close

def close() -> None

Close the sync pools; async pools too when no event loop is running here.

connection

def connection(target: str | None = None) -> Iterator[psycopg.Connection]

One pooled connection, returned on exit — the atom every op rides.

from_env

@classmethod
def from_env(prefix: str = 'POSTGRES', **kw: Any) -> Self

Build the primary, configs, and bounded monitoring targets from env.

POSTGRES_* remains the one credential/address contract. Configs and monitoring use the same server identity with only their physical databases changed via POSTGRES_CONFIGS_DB (default configs) and POSTGRES_MONITORING_DB (default monitoring). Monitoring also has a bounded five-second connection and statement timeout. Callers therefore get correct multi-database routing from plain DBClient.from_env().

new_batch_id

@staticmethod
def new_batch_id() -> str

on

def on(target: str) -> Iterator[Self]

Temporarily route to another target: with db.on("monitoring"): db.append(...). Context-scoped: only this task (and the threads its ops hop to) is rerouted — concurrent tasks keep their own target.

ping

def ping(target: str | None = None) -> bool

Liveness — SELECT 1 through the pool.

server_version

def server_version(target: str | None = None) -> int

The server’s major version — posture checks and feature gates.

tx

def tx(target: str | None = None) -> Iterator[psycopg.Connection]

One explicit TRANSACTION scope — everything inside commits together or not at all (one commit boundary per logical op, the legacy mid-flow-commit disease’s antidote).

Types and values

logger

logger = structlog.get_logger()