common_db.client.client
client.py — DBClient: THE user-facing front door.
Today Postgres is the one backend, so DBClient IS the PG engine with the construction surface on top (recorded decision: when duckdb/falkor arrive as registry axis values, this class becomes the routing wrapper and the ops stay identical — consumers never change a line).
THE ASYNC FACE (recorded decision): every op has an a-prefixed twin that
delegates through asyncio.to_thread — full async semantics (the event
loop never blocks; jobs await like they await feeds) with ZERO drift risk
between faces, because there is exactly one implementation. The twins carry
the REAL signatures (mirrored from the sync ops verbatim) so the async face
is introspectable — IDEs, help(), and reviewers see the true surface, never
*args. A native AsyncConnectionPool port is a contained future upgrade if
profiling ever demands it; the surface will not change.
db = DBClient.from_env() # POSTGRES_* -> one targetdb = DBClient(targets={"prices": ..., "monitoring": ...})with db, db.on("monitoring"): db.append(rows, "monitoring.stage_audit")result = await db.aupsert(frame, "raw.bars") # the async faceClasses
DBClient
Bases: PGClient, ArchiveClient
The suite’s front door — full op surface (sync + async faces), construction classmethods, multi-target routing. Op mechanics: PGClient for the PG store, ArchiveClient for the pq/dataset store (the storage law’s two legs behind ONE handle).
aappend
async def aappend(data: Any, table: TableRef | str, *, config: WriteConfig | None = None, target: str | None = None) -> WriteResultaarchive
async def aarchive(data: Any, ref: DatasetRef | str, *, partition_by: tuple[str, ...] | None = None, config: WriteConfig | None = None, batch_id: str | None = None, partition_snapshot: bool = False) -> WriteResultaassess
async def aassess(data: Any, table: TableRef | str, *, on: tuple[str, ...] | None = None, scope: dict[str, Any] | None = None, target: str | None = None) -> AssessmentReportacombine
async def acombine(sources: list[TableRef | str], into: TableRef | str, *, replace: bool = True, target: str | None = None) -> WriteResultaensure
async def aensure(schema: DBSchemaBuilder | sa.Table, *, target: str | None = None) -> Noneakey_upgrade
async def akey_upgrade(data: Any, table: TableRef | str, *, match_on: tuple[str, ...], placeholder: dict[str, Any], config: WriteConfig | None = None, target: str | None = None) -> WriteResultaping
async def aping(target: str | None = None) -> boolaquery
async def aquery(statement: str | sql.SQL | sql.Composed, params: dict[str, Any] | tuple | None = None, *, config: ReadConfig | None = None, target: str | None = None) -> ReadResultaread
async def aread(table: TableRef | str, *, columns: tuple[str, ...] | None = None, where: dict[str, Any] | None = None, latest_per: tuple[str, ...] | None = None, order: str | tuple[str, ...] | None = None, descending: bool = False, limit: int | None = None, config: ReadConfig | None = None, target: str | None = None) -> ReadResultareconcile
async def areconcile(data: Any, table: TableRef | str, *, scope: dict[str, Any], on: tuple[str, ...] | None = None, update_cols: tuple[str, ...] | None = None, coalesce: tuple[str, ...] = (), on_missing: ReconcilePolicy | str | None = None, config: WriteConfig | None = None, target: str | None = None) -> ReconcileReportareplace
async def areplace(data: Any, table: TableRef | str, *, scope: dict[str, Any] | None = None, full: bool = False, config: WriteConfig | None = None, target: str | None = None) -> WriteResultareplace_archive_partitions
async def areplace_archive_partitions(data: Any, ref: DatasetRef | str, *, partition_by: tuple[str, ...], manifest: Sequence[Mapping[str, Any]], config: WriteConfig | None = None) -> WriteResultareplace_many
async def areplace_many(replacements: list[tuple[Any, TableRef | str, WriteConfig | None]], *, target: str | None = None) -> tuple[WriteResult, ...]areplace_partitions
async def areplace_partitions(data: Any, table: TableRef | str, *, partition_by: tuple[str, ...], config: WriteConfig | None = None, target: str | None = None) -> WriteResultaretrieve
async def aretrieve(name: str, *, key: dict[str, Any] | None = None, table: TableRef | str = 'public.stash', target: str | None = None) -> Anyascan
async def ascan(ref: DatasetRef | str, *, columns: tuple[str, ...] | None = None, where: dict[str, Any] | None = None, config: ReadConfig | None = None, lazy: bool = False) -> ReadResultaserver_version
async def aserver_version(target: str | None = None) -> intastash
async def astash(name: str, obj: Any, *, key: dict[str, Any] | None = None, table: TableRef | str = 'public.stash', prune_days: int | None = 7, target: str | None = None) -> WriteResultaupsert
async def aupsert(data: Any, table: TableRef | str, *, on: tuple[str, ...] | None = None, update_cols: tuple[str, ...] | None = None, coalesce: tuple[str, ...] = (), config: WriteConfig | None = None, target: str | None = None) -> WriteResultaupsert_append
async def aupsert_append(upsert_data: Any, append_data: Any, table: TableRef | str, *, on: tuple[str, ...] | None = None, update_cols: tuple[str, ...] | None = None, coalesce: tuple[str, ...] = (), config: WriteConfig | None = None, target: str | None = None) -> WriteResult