loom.core.sql.abc

Abstraction layer of the SQL subsystem: port, options, envelopes and errors.

exception loom.core.sql.abc.RoleNotAllowedError(role, *, connection)

Bases: Forbidden

Raised when the caller role is not in the connection allowlist.

Without a configured allowlist every caller-provided role is rejected (fail-closed policy).

Parameters:

• role (str) – Role requested by the caller.

• connection (str) – Name of the connection that rejected the role.

Return type:

None

exception loom.core.sql.abc.RoleRequiredError(connection)

Bases: Forbidden

Raised when no effective role can be resolved for a query.

A query never runs with the full default roles of the connection user: without a caller role and without default_role execution is refused.

Parameters:

connection (str) – Name of the connection lacking an effective role.

Return type:

None

exception loom.core.sql.abc.RolesNotBoundError(connection)

Bases: Forbidden

Raised when the verified identity yields no allowed role.

Covers every fail-closed outcome of identity binding — no verified claims, a missing, empty or wrongly typed roles claim, or an empty intersection with the connection allowlist. The message is deliberately uniform so the response never reveals which part of the token failed; the precise reason is logged server-side.

Parameters:

connection (str) – Name of the connection that refused the request.

Return type:

None

class loom.core.sql.abc.SqlColumn(*, name, type)

Bases: LoomFrozenStruct

Column descriptor of a SQL result set.

Parameters:

• name (str)

• type (str)

name

Column name as reported by the backend.

Type:

str

type

Native backend type (e.g. "DateTime64(3)").

Type:

str

exception loom.core.sql.abc.SqlExecutionError(message)

Bases: RuleViolation

Raised when the backend rejects a SQL statement.

Carries a sanitized message (backend error code plus first line, without host, DSN or stack trace).

Parameters:

message (str) – Sanitized backend rejection message.

Return type:

None

class loom.core.sql.abc.SqlExecutionOptions(*, roles=(), readonly=True, limit=None, offset=0, max_execution_time=30)

Bases: LoomFrozenStruct

Backend-agnostic execution options resolved by the service policy.

Each executor translates these values to its native per-query mechanism (for ClickHouse: per-query settings). The policy applies them last, so connection-level settings can never override them.

Parameters:

• roles (tuple[str, ...])

• readonly (bool)

• limit (int | None)

• offset (int)

• max_execution_time (int)

roles

Effective roles for this single query, already validated against the connection allowlist. Several roles apply the union of their privileges; empty means no role at all (internal probes only).

Type:

tuple[str, …]

readonly

Whether the query must run in read-only mode.

Type:

bool

limit

Maximum number of rows to return. The executor requests limit + 1 rows to compute has_more.

Type:

int | None

offset

Number of rows to skip before returning results.

Type:

int

max_execution_time

Per-query execution timeout in seconds.

Type:

int

class loom.core.sql.abc.SqlExecutor(*args, **kwargs)

Bases: Protocol

Port implemented by concrete SQL backends.

Exists for dependency inversion (the service never imports driver code) and for testing with fakes. Documented as a contract in evolution until a second backend implementation lands.

async execute(sql, *, parameters=None, options)

Execute sql with server-side bound parameters under options.

Parameters:

• sql (str) – SQL statement with native parameter placeholders.

• parameters (Mapping[str, Any] | None) – Values bound server-side; never interpolated locally.

• options (SqlExecutionOptions) – Policy-resolved execution options for this single query.

Returns:

The standard tabular result envelope.

Raises:

SqlExecutionError – When the backend rejects the statement.

Return type:

SqlQueryResult

class loom.core.sql.abc.SqlQueryResult(*, columns, rows, row_count, limit, offset, has_more, elapsed_ms)

Bases: LoomFrozenStruct

Standard tabular envelope returned for any SQL statement.

Parameters:

• columns (tuple[SqlColumn, ...])

• rows (tuple[tuple[Any, ...], ...])

• row_count (int)

• limit (int)

• offset (int)

• has_more (bool)

• elapsed_ms (float)

columns

Ordered column descriptors of the result set.

Type:

tuple[loom.core.sql.abc.contracts.SqlColumn, …]

rows

Result rows, already trimmed to limit.

Type:

tuple[tuple[Any, …], …]

row_count

Number of rows in rows.

Type:

int

limit

Effective limit applied to this page.

Type:

int

offset

Effective offset applied to this page.

Type:

int

has_more

Whether more rows exist beyond this page.

Type:

bool

elapsed_ms

Server-side execution telemetry in milliseconds.

Type:

float

exception loom.core.sql.abc.UnknownConnectionError(connection)

Bases: NotFound

Raised when a SQL connection name is not configured.

Parameters:

connection (str) – Name of the missing connection.

Return type:

None