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') -> NoneFields and properties declared here; inherited members belong to the bases above.
active_target
Read-only property.
active_target: stris_open
Read-only property.
is_open: boolmax_pool_size
Read-only property.
max_pool_size: intMaximum connections available to one named target pool.
targets
Read-only property.
targets: tuple[str, ...]aclose
async def aclose() -> NoneClose 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) -> boolLiveness 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() -> NoneClose 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
@classmethoddef from_env(prefix: str = 'POSTGRES', **kw: Any) -> SelfBuild 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
@staticmethoddef new_batch_id() -> stron
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) -> boolLiveness — SELECT 1 through the pool.
server_version
def server_version(target: str | None = None) -> intThe 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()