Skip to content

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 target
db = DBClient(targets={"prices": ..., "monitoring": ...})
with db, db.on("monitoring"):
db.append(rows, "monitoring.stage_audit")
result = await db.aupsert(frame, "raw.bars") # the async face

Classes

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) -> WriteResult

aarchive

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) -> WriteResult

aassess

async def aassess(data: Any, table: TableRef | str, *, on: tuple[str, ...] | None = None, scope: dict[str, Any] | None = None, target: str | None = None) -> AssessmentReport

acombine

async def acombine(sources: list[TableRef | str], into: TableRef | str, *, replace: bool = True, target: str | None = None) -> WriteResult

aensure

async def aensure(schema: DBSchemaBuilder | sa.Table, *, target: str | None = None) -> None

akey_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) -> WriteResult

aping

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

aquery

async def aquery(statement: str | sql.SQL | sql.Composed, params: dict[str, Any] | tuple | None = None, *, config: ReadConfig | None = None, target: str | None = None) -> ReadResult

aread

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) -> ReadResult

areconcile

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) -> ReconcileReport

areplace

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) -> WriteResult

areplace_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) -> WriteResult

areplace_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) -> WriteResult

aretrieve

async def aretrieve(name: str, *, key: dict[str, Any] | None = None, table: TableRef | str = 'public.stash', target: str | None = None) -> Any

ascan

async def ascan(ref: DatasetRef | str, *, columns: tuple[str, ...] | None = None, where: dict[str, Any] | None = None, config: ReadConfig | None = None, lazy: bool = False) -> ReadResult

aserver_version

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

astash

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) -> WriteResult

aupsert

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) -> WriteResult

aupsert_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