Platforms¶

base ¶

PlatformAdapter Protocol: the contract every platform integration implements.

PlatformAdapter ¶

Bases: Protocol

Executes SQL against a data platform; returns rows + schema + latency.

Required behavior

On success: return ExecutionSuccess with rows populated and schema_ populated — a TypedSchema (each Column.type a SqlType built from the driver's native type string in the adapter's static dialect), or an UntypedSchema (names only) when the driver reports no result-column types — with non-negative latency_seconds.
On query failure: return ExecutionFailure with an error describing the failure and non-negative latency_seconds. Do NOT raise.
latency_seconds measures wall-clock time spent inside execute().

execute ¶

execute(sql: str) -> ExecutionResult

Execute one SQL statement and return its structured result.

cancel ¶

cancel() -> None

Abort the query currently executing on this connection, if any.

Must be safe to call from another thread while execute is blocked. A no-op when no query is running, and best-effort: it must not raise — a cancellation that fails or arrives late is non-fatal.

close ¶

close() -> None

Release the underlying connection/resources.

NativeTimeoutAdapter ¶

Bases: Protocol

Capability for executing one statement with a backend-native deadline.

execute_with_timeout ¶

execute_with_timeout(
    sql: str, timeout_seconds: float
) -> ExecutionResult

Execute sql once with a backend-native timeout.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The SQL statement to execute.	required
`timeout_seconds`	`float`	The positive statement deadline in seconds.	required

Returns:

Type	Description
`ExecutionResult`	The structured execution result.

ReusableStateAdapter ¶

Bases: Protocol

Capability for reporting whether local session state remains reusable.

is_reusable ¶

is_reusable() -> bool

Return local, non-I/O session reuse state.

TypeResolvingAdapter ¶

Bases: Protocol

Capability for backends whose execute().schema_ reports types with unresolved parameters.

Implemented only by adapters whose driver drops type parameters (e.g. a DECIMAL scale or an ARRAY element type); precise backends do not implement it. Both methods must be pure (no I/O): one produces the SQL that probes for precise types, the other interprets that probe's result rows. The caller runs the probe.

type_probe_sql ¶

type_probe_sql(sql: str) -> str

Build the probe statement that recovers precise types for sql's projection.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The statement whose projected column types to resolve.	required

Returns:

Type	Description
`str`	A probe statement for the caller to execute; its rows feed `types_from_probe`.

types_from_probe ¶

types_from_probe(
    rows: list[dict[str, Any]],
) -> list[SqlType] | ExecutionError

Parse the probe's result rows into precise SqlTypes, one per projected column.

They must be returned in the order the query projects its columns.

Parameters:

Name	Type	Description	Default
`rows`	`list[dict[str, Any]]`	The rows returned by executing `type_probe_sql`, in projection order.	required

Returns:

Type	Description
`list[SqlType] \| ExecutionError`	One precise `SqlType` per projected column, in order, or an `ExecutionError` when
`list[SqlType] \| ExecutionError`	the rows cannot yield types.

BudgetedExecutionAdapter ¶

Bases: Protocol

Capability for a pool lease that owns bounded execution lifecycle state.

execute_within_budget ¶

execute_within_budget(
    sql: str,
    max_seconds: float,
    *,
    cancel_grace_seconds: float | None,
) -> ExecutionResult

Execute sql with the lease's timeout and quarantine handling.

execute_within_budget ¶

execute_within_budget(
    adapter: PlatformAdapter,
    sql: str,
    max_seconds: float | None,
    *,
    cancel_grace_seconds: float | None = None,
) -> ExecutionResult

Execute sql on adapter, cancelling it if it exceeds max_seconds.

With max_seconds unset, runs adapter.execute directly. Otherwise runs it on a daemon worker thread and waits up to max_seconds. At expiry, cancellation runs independently, then the caller waits at most cancel_grace_seconds before returning a budget error. Pool leases own the corresponding quarantine and deferred-close lifecycle.

Parameters:

Name	Type	Description	Default
`adapter`	`PlatformAdapter`	The platform adapter to execute against.	required
`sql`	`str`	The SQL statement to execute.	required
`max_seconds`	`float \| None`	Wall-clock ceiling for the query, or `None` for no limit.	required
`cancel_grace_seconds`	`float \| None`	Extra time to allow cancellation to finish after expiry. Defaults to one second for direct adapters; pool leases use their configured policy.	`None`

Returns:

Type	Description
`ExecutionResult`	The adapter's execution outcome if the query finishes within budget, otherwise an
`ExecutionResult`	`ExecutionFailure` with `latency_seconds` measuring the elapsed time.

execution_error ¶

execution_error(
    exc: Exception,
    kind: ExecutionErrorKind = "query_failed",
) -> ExecutionError

Translate a driver exception into a typed ExecutionError, preserving structured detail.

Reads whatever structured attributes the exception happens to expose — SQLSTATE, an error condition/class, message parameters — by duck-typing, so no driver package is imported or enumerated and no driver message is parsed. The live exception is kept as cause for debugging; message falls back to the exception's class name when its string form is empty.

Parameters:

Name	Type	Description	Default
`exc`	`Exception`	The driver exception to translate.	required
`kind`	`ExecutionErrorKind`	The `ExecutionError` classifier to assign.	`'query_failed'`

Returns:

Type	Description
`ExecutionError`	An `ExecutionError` carrying `kind`, a non-empty `message`, any recovered structured
`ExecutionError`	fields, and `exc` as `cause`.

rows_or_error ¶

rows_or_error(
    columns: list[Column],
    rows_raw: list[tuple[Any, ...]],
    latency_seconds: float,
) -> ExecutionResult

Build a successful typed ExecutionResult, or an error one if column names collide.

Parameters:

Name	Type	Description	Default
`columns`	`list[Column]`	The result-set columns, in order, as reported by the driver.	required
`rows_raw`	`list[tuple[Any, ...]]`	The positional row tuples, aligned with `columns`.	required
`latency_seconds`	`float`	Wall-clock time spent executing the query.	required

Returns:

Type	Description
`ExecutionResult`	An `ExecutionResult` with name-keyed rows and a `TypedSchema`, or `error` set (and no
`ExecutionResult`	rows or schema) when one or more column names are duplicated.

untyped_rows_or_error ¶

untyped_rows_or_error(
    names: list[str],
    rows_raw: list[tuple[Any, ...]],
    latency_seconds: float,
) -> ExecutionResult

Build a successful untyped ExecutionResult, or an error one if column names collide.

For engines whose driver reports no result-column types (e.g. SQLite): the schema carries column names only.

Parameters:

Name	Type	Description	Default
`names`	`list[str]`	The result-column names, in order, as reported by the driver.	required
`rows_raw`	`list[tuple[Any, ...]]`	The positional row tuples, aligned with `names`.	required
`latency_seconds`	`float`	Wall-clock time spent executing the query.	required

Returns:

Type	Description
`ExecutionResult`	An `ExecutionResult` with name-keyed rows and an `UntypedSchema`, or `error` set (and
`ExecutionResult`	no rows or schema) when one or more column names are duplicated.

registry ¶

Platform-reference builders and PlatformRef -> live PlatformAdapter resolution.

duckdb_platform ¶

duckdb_platform(
    name: str,
    path: str = ":memory:",
    *,
    pool: PoolPolicy | None = None,
) -> DuckDBPlatformRef

Build a PlatformRef for an in-process DuckDB database.

Parameters:

Name	Type	Description	Default
`name`	`str`	A unique name identifying this platform connection.	required
`path`	`str`	The DuckDB database path. Defaults to `:memory:` (in-process).	`':memory:'`
`pool`	`PoolPolicy \| None`	Optional connection lifecycle policy.	`None`

Returns:

Type	Description
`DuckDBPlatformRef`	A serializable `PlatformRef` for the DuckDB database. Building the ref needs no
`DuckDBPlatformRef`	driver.

sqlite_platform ¶

sqlite_platform(
    name: str,
    path: str = ":memory:",
    *,
    pool: PoolPolicy | None = None,
) -> SQLitePlatformRef

Build a PlatformRef for an in-process SQLite database.

Parameters:

Name	Type	Description	Default
`name`	`str`	A unique name identifying this platform connection.	required
`path`	`str`	The SQLite database path. Defaults to `:memory:` (in-process).	`':memory:'`
`pool`	`PoolPolicy \| None`	Optional connection lifecycle policy.	`None`

Returns:

Type	Description
`SQLitePlatformRef`	A serializable `PlatformRef` for the SQLite database. Building the ref needs no driver
`SQLitePlatformRef`	(SQLite ships with the standard library).

postgres_platform ¶

postgres_platform(
    name: str,
    conninfo: str = "",
    *,
    pool: PoolPolicy | None = None,
) -> PostgreSQLPlatformRef

Build a PlatformRef for a PostgreSQL database.

Parameters:

Name	Type	Description	Default
`name`	`str`	A unique name identifying this platform connection.	required
`conninfo`	`str`	A libpq connection string (keyword/value or `postgresql://` URI). Empty uses libpq defaults / `PG*` env vars.	`''`
`pool`	`PoolPolicy \| None`	Optional connection lifecycle policy.	`None`

Returns:

Type	Description
`PostgreSQLPlatformRef`	A serializable `PlatformRef` for the PostgreSQL database. Building the ref needs no
`PostgreSQLPlatformRef`	driver.

databricks_platform ¶

databricks_platform(
    name: str,
    *,
    server_hostname: str,
    http_path: str,
    catalog: str | None = None,
    schema: str | None = None,
    pool: PoolPolicy | None = None,
) -> DatabricksPlatformRef

Build a PlatformRef for a Databricks SQL Warehouse.

Holds only non-secret connection details; credentials are not included here.

Parameters:

Name	Type	Description	Default
`name`	`str`	A unique name identifying this platform connection.	required
`server_hostname`	`str`	The workspace hostname (no scheme), e.g. `dbc-xxxx.cloud.databricks.com`.	required
`http_path`	`str`	The SQL Warehouse HTTP path, e.g. `/sql/1.0/warehouses/<id>`.	required
`catalog`	`str \| None`	The default catalog, or `None` to leave the session default.	`None`
`schema`	`str \| None`	The default schema, or `None` to leave the session default.	`None`
`pool`	`PoolPolicy \| None`	Optional connection lifecycle policy.	`None`

Returns:

Type	Description
`DatabricksPlatformRef`	A serializable `PlatformRef` for the Databricks warehouse. Building the ref needs no
`DatabricksPlatformRef`	driver.

snowflake_platform ¶

snowflake_platform(
    name: str,
    *,
    account: str,
    user: str | None = None,
    warehouse: str | None = None,
    role: str | None = None,
    database: str | None = None,
    schema: str | None = None,
    authenticator: str | None = None,
    workload_identity_provider: str | None = None,
    pool: PoolPolicy | None = None,
) -> SnowflakePlatformRef

Build a PlatformRef for a Snowflake account.

Holds only non-secret connection details; credentials are not included here.

Parameters:

Name	Type	Description	Default
`name`	`str`	A unique name identifying this platform connection.	required
`account`	`str`	The Snowflake account identifier.	required
`user`	`str \| None`	The Snowflake user name, or `None` to rely on `authenticator`.	`None`
`warehouse`	`str \| None`	The default warehouse, or `None` to leave the session default.	`None`
`role`	`str \| None`	The default role, or `None` to leave the session default.	`None`
`database`	`str \| None`	The default database, or `None` to leave the session default.	`None`
`schema`	`str \| None`	The default schema, or `None` to leave the session default.	`None`
`authenticator`	`str \| None`	The authenticator to use (e.g. `"externalbrowser"`, `"oauth"`, `"workload_identity"`), or `None` for the connector's default.	`None`
`workload_identity_provider`	`str \| None`	The workload identity provider (e.g. `"OIDC"`) when `authenticator` is `"workload_identity"`, or `None` otherwise.	`None`
`pool`	`PoolPolicy \| None`	Optional connection lifecycle policy.	`None`

Returns:

Type	Description
`SnowflakePlatformRef`	A serializable `PlatformRef` for the Snowflake account. Building the ref needs no
`SnowflakePlatformRef`	driver.

bigquery_platform ¶

bigquery_platform(
    name: str,
    *,
    project: str,
    dataset: str | None = None,
    location: str | None = None,
    pool: PoolPolicy | None = None,
) -> BigQueryPlatformRef

Build a PlatformRef for a BigQuery project.

Holds only non-secret connection details; credentials are not included here.

Parameters:

Name	Type	Description	Default
`name`	`str`	A unique name identifying this platform connection.	required
`project`	`str`	The Google Cloud project to run jobs and bill against.	required
`dataset`	`str \| None`	The default dataset for unqualified table names, or `None` to leave none.	`None`
`location`	`str \| None`	The location to run jobs in (e.g. `"US"`, `"EU"`), or `None` for the client default.	`None`
`pool`	`PoolPolicy \| None`	Optional connection lifecycle policy.	`None`

Returns:

Type	Description
`BigQueryPlatformRef`	A serializable `PlatformRef` for the BigQuery project. Building the ref needs no driver.

pool_for ¶

pool_for(ref: PlatformRef) -> ConnectionPool

Return the connection pool for ref.name, building and caching one on first use.

Reuses the cached pool on subsequent calls for the same ref.name.

Parameters:

Name	Type	Description	Default
`ref`	`PlatformRef`	The platform reference to resolve a pool for.	required

Returns:

Type	Description
`ConnectionPool`	The `ConnectionPool` for `ref`, cached and reused across calls.

Raises:

Type	Description
`ValueError`	If `ref.name` is already bound to a different configuration.

resolve ¶

resolve(ref: PlatformRef) -> PlatformAdapter

Return ref's dedicated utility adapter, building its pool on first use.

The utility adapter is for seeding, doctor, and direct execution; it is never a checkout member, so its use never contends with concurrent case execution. Concurrent execution goes through acquired.

Parameters:

Name	Type	Description	Default
`ref`	`PlatformRef`	The platform reference to resolve.	required

Returns:

Type	Description
`PlatformAdapter`	The utility `PlatformAdapter` for `ref`, cached and reused across calls.

acquired ¶

acquired(ref: PlatformRef) -> Iterator[PlatformAdapter]

Check out one of ref's pool members for the duration of the with block.

Yields a member reserved exclusively for the caller, returned to the pool on exit even if the block raises. Concurrent callers each get a distinct member, blocking once the pool's per-engine size is reached.

Parameters:

Name	Type	Description	Default
`ref`	`PlatformRef`	The platform reference whose pool to acquire a member from.	required

Yields:

Type	Description
`PlatformAdapter`	A `PlatformAdapter` reserved for the caller until the block exits.

close_all ¶

close_all() -> None

Close every cached pool and clear the cache (idempotent; no-op when empty).

duckdb ¶

DuckDBAdapter: in-process DuckDB execution backend.

DuckDBAdapter ¶

DuckDBAdapter(database: str = ':memory:')

Executes SQL against an in-process DuckDB database.

Open a DuckDB connection to database (default :memory:).

from_connection `classmethod` ¶

from_connection(
    connection: DuckDBPyConnection,
) -> DuckDBAdapter

Build an adapter over an existing DuckDB connection or .cursor() handle.

The handle is adopted as-is rather than reopened, so sibling cursors of one parent share its in-process database. close releases only this handle, never a parent it was cursored from.

Parameters:

Name	Type	Description	Default
`connection`	`DuckDBPyConnection`	A live DuckDB connection or cursor handle to execute against.	required

Returns:

Type	Description
`DuckDBAdapter`	A `DuckDBAdapter` bound to `connection`.

cancel ¶

cancel() -> None

Interrupt the query currently executing on this connection.

Safe to call from another thread while execute is blocked, and a no-op when no query is running. The interrupted execute raises duckdb.InterruptException, which it surfaces as an ExecutionFailure like any other query failure.

close ¶

close() -> None

Release the underlying DuckDB connection (file handle / WAL lock).

Explicit close matters on Windows, where WAL locks make implicit cleanup unreliable.

execute ¶

execute(sql: str) -> ExecutionResult

Execute one SQL statement against the database.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The SQL statement to execute.	required

Returns:

Type	Description
`ExecutionResult`	An `ExecutionResult` with the returned rows, schema, and latency. Query
`ExecutionResult`	failures are returned as an `ExecutionFailure` rather than raised.

is_disconnect ¶

is_disconnect(error: ExecutionError) -> bool

Return whether DuckDB reported a fatal or disconnected connection.

postgres ¶

PostgresAdapter: PostgreSQL execution backend over psycopg (v3).

PostgresAdapter ¶

PostgresAdapter(conninfo: str = '')

Executes SQL against a PostgreSQL database via psycopg (v3).

Open a psycopg connection.

conninfo is a libpq connection string — keyword/value ("host=... port=... user=... password=... dbname=...") or a postgresql:// URI. Empty uses libpq defaults / PG* env vars.

cancel ¶

cancel() -> None

Cancel the current query without raising cancellation errors.

close ¶

close() -> None

Release the underlying psycopg connection.

execute ¶

execute(sql: str) -> ExecutionResult

Execute one SQL statement against the database.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The SQL statement to execute.	required

Returns:

Type	Description
`ExecutionResult`	An `ExecutionResult` with the returned rows, schema, and latency. Query
`ExecutionResult`	failures are returned as an `ExecutionFailure` rather than raised.

execute_with_timeout ¶

execute_with_timeout(
    sql: str, timeout_seconds: float
) -> ExecutionResult

Execute one statement with PostgreSQL's native statement timeout.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The SQL statement to execute.	required
`timeout_seconds`	`float`	Positive statement deadline in seconds.	required

Returns:

Type	Description
`ExecutionResult`	The statement result, mapping SQLSTATE `57014` to `budget_exceeded`.

is_reusable ¶

is_reusable() -> bool

Return whether local timeout-setting cleanup has completed successfully.

ping ¶

ping() -> bool

Return whether this PostgreSQL session can execute a simple statement.

is_disconnect ¶

is_disconnect(error: ExecutionError) -> bool

Return whether a structured error or connection state proves disconnection.

databricks ¶

DatabricksAdapter: Databricks SQL Warehouse execution backend over databricks-sql-connector.

DatabricksAdapter ¶

DatabricksAdapter(
    *,
    server_hostname: str,
    http_path: str,
    catalog: str | None = None,
    schema: str | None = None,
)

Executes SQL against a Databricks SQL Warehouse via databricks-sql-connector.

Open a Databricks SQL connection.

Credentials are not passed here.

Parameters:

Name	Type	Description	Default
`server_hostname`	`str`	The workspace hostname (no scheme), e.g. `dbc-xxxx.cloud.databricks.com`.	required
`http_path`	`str`	The SQL Warehouse HTTP path, e.g. `/sql/1.0/warehouses/<id>`.	required
`catalog`	`str \| None`	The default catalog, or `None` to leave the session default.	`None`
`schema`	`str \| None`	The default schema, or `None` to leave the session default.	`None`

cancel ¶

cancel() -> None

Cancel the query currently executing on this connection, if any.

Safe to call from another thread while execute is blocked; best-effort, so all failures are swallowed.

close ¶

close() -> None

Release the underlying Databricks connection.

execute ¶

execute(sql: str) -> ExecutionResult

Execute one SQL statement against the warehouse.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The SQL statement to execute.	required

Returns:

Type	Description
`ExecutionResult`	An `ExecutionResult` with the returned rows, schema, and latency. Query
`ExecutionResult`	failures are returned as an `ExecutionFailure` rather than raised.

ping ¶

ping() -> bool

Return whether the open connection can execute a simple statement.

is_disconnect ¶

is_disconnect(error: ExecutionError) -> bool

Return whether a transport or closed-session error makes this connection unusable.

type_probe_sql `staticmethod` ¶

type_probe_sql(sql: str) -> str

Build the DESCRIBE QUERY probe that recovers precise types for sql.

cursor.description drops parametric type parameters (a DECIMAL scale, an ARRAY element type); DESCRIBE QUERY reports the precise data_type per column without running the query.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The statement whose projected column types to resolve.	required

Returns:

Type	Description
`str`	A `DESCRIBE QUERY` statement wrapping `sql` (trailing `;` stripped, which it rejects).

types_from_probe `staticmethod` ¶

types_from_probe(
    rows: list[dict[str, Any]],
) -> list[SqlType] | ExecutionError

Parse DESCRIBE QUERY rows into precise SqlTypes, in projection order.

Parameters:

Name	Type	Description	Default
`rows`	`list[dict[str, Any]]`	The rows returned by executing `type_probe_sql`, in projection order.	required

Returns:

Type	Description
`list[SqlType] \| ExecutionError`	One precise `SqlType` per projected column, in order, or an `ExecutionError` when
`list[SqlType] \| ExecutionError`	the probe returns no rows or a row without a `data_type`.

bigquery ¶

BigQueryAdapter: BigQuery execution backend over google-cloud-bigquery.

BigQueryAdapter ¶

BigQueryAdapter(
    *,
    project: str,
    dataset: str | None = None,
    location: str | None = None,
)

Executes SQL against BigQuery via google-cloud-bigquery.

Open a BigQuery client.

Credentials are not passed here; they resolve through Application Default Credentials.

Parameters:

Name	Type	Description	Default
`project`	`str`	The Google Cloud project to run jobs and bill against.	required
`dataset`	`str \| None`	The default dataset for unqualified table names, or `None` to leave none.	`None`
`location`	`str \| None`	The location to run jobs in (e.g. `"US"`, `"EU"`), or `None` for the client default.	`None`

client `property` ¶

client: Client

The live BigQuery client backing this adapter.

cancel ¶

cancel() -> None

Cancel the job currently executing on this client, if any.

Safe to call from another thread while execute is blocked; best-effort, so all failures are swallowed.

close ¶

close() -> None

Release the underlying BigQuery client.

execute ¶

execute(sql: str) -> ExecutionResult

Execute one SQL statement against BigQuery.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The SQL statement to execute.	required

Returns:

Type	Description
`ExecutionResult`	An `ExecutionResult` with the returned rows, schema, and latency. Query
`ExecutionResult`	failures are returned as an `ExecutionFailure` rather than raised.

execute_with_timeout ¶

execute_with_timeout(
    sql: str, timeout_seconds: float
) -> ExecutionResult

Submit one job with BigQuery's native job deadline.

Parameters:

Name	Type	Description	Default
`sql`	`str`	The SQL statement to execute.	required
`timeout_seconds`	`float`	Positive job deadline in seconds.	required

Returns:

Type	Description
`ExecutionResult`	The structured job result.

Platforms¶

base ¶

PlatformAdapter ¶

execute ¶

cancel ¶

close ¶

NativeTimeoutAdapter ¶

execute_with_timeout ¶

ReusableStateAdapter ¶

is_reusable ¶

TypeResolvingAdapter ¶

type_probe_sql ¶

types_from_probe ¶

BudgetedExecutionAdapter ¶

execute_within_budget ¶

execute_within_budget ¶

execution_error ¶

rows_or_error ¶

untyped_rows_or_error ¶

registry ¶

duckdb_platform ¶

sqlite_platform ¶

postgres_platform ¶

databricks_platform ¶

snowflake_platform ¶

bigquery_platform ¶

pool_for ¶

resolve ¶

acquired ¶

close_all ¶

duckdb ¶

DuckDBAdapter ¶

from_connection classmethod ¶

cancel ¶

close ¶

execute ¶

is_disconnect ¶

postgres ¶

PostgresAdapter ¶

cancel ¶

close ¶

execute ¶

execute_with_timeout ¶

is_reusable ¶

ping ¶

is_disconnect ¶

databricks ¶

DatabricksAdapter ¶

cancel ¶

close ¶

execute ¶

ping ¶

is_disconnect ¶

type_probe_sql staticmethod ¶

types_from_probe staticmethod ¶

bigquery ¶

BigQueryAdapter ¶

client property ¶

cancel ¶

close ¶

execute ¶

execute_with_timeout ¶

from_connection `classmethod` ¶

type_probe_sql `staticmethod` ¶

types_from_probe `staticmethod` ¶

client `property` ¶