loom.core.sql.clickhouse

ClickHouse backend for the SQL subsystem (optional extra loom-kernel[clickhouse]).

Provides ClickHouseSqlExecutor, the ClickHouse implementation of the SqlExecutor port, and ClickHouseConnectionRegistry, the async context manager owning client lifecycle, the per-query role support assertion and the fail-closed sentinel-role startup probe.

class loom.core.sql.clickhouse.ClickHouseConnectionRegistry(*, config, client_factory=None)

Bases: object

Owns the ClickHouse clients and executors for every named connection.

Usable only as an async context manager: clients exist between __aenter__ and __aexit__, which eliminates any intermediate started/stopped state. Startup is fail-closed: a driver without per-query role support or a server that silently ignores roles aborts the enter and closes everything created so far.

Parameters:

• config (SqlConfig) – Parsed sql: section with the named connections.

• client_factory (ClickHouseClientFactory | None) – Factory receiving the exact get_async_client keyword arguments. Defaults to the real driver factory.

Example:

async with ClickHouseConnectionRegistry(config=sql_config) as registry:
    executor = registry.executor("analytics")

classmethod from_config(raw)

Build a registry from the raw sql: section mapping.

Parameters:

raw (Mapping[str, Any]) – Mapping shaped like the sql: config section ({"connections": {...}}).

Returns:

A registry over the validated configuration.

Raises:

ConfigError – When the mapping fails SqlConfig validation.

Return type:

Self

executor(name)

Return the executor of the connection name.

Parameters:

name (str) – Configured connection name.

Returns:

The executor bound to that connection.

Raises:

• RuntimeError – When the registry was not entered as a context.

• UnknownConnectionError – When name is not configured.

Return type:

ClickHouseSqlExecutor

class loom.core.sql.clickhouse.ClickHouseSqlExecutor(*, client, config)

Bases: object

Executes SQL on one ClickHouse connection with per-query policy settings.

Translates SqlExecutionOptions into native per-query settings merged last over the connection settings, so the policy (role, readonly, limits) can never be overridden. Pagination requests limit + 1 rows to compute has_more and relies on the max_result_rows backstop with result_overflow_mode='throw' (never truncate silently). The client is never mutated between queries: isolation relies exclusively on per-query settings.

Parameters:

• client (AsyncClickHouseClient) – Async ClickHouse client bound to this connection.

• config (SqlConnectionConfig) – Connection configuration providing limits and extra settings.

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

Execute sql with server-side bound parameters under options.

Parameters:

• sql (str) – SQL statement with native {name:Type} placeholders.

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

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

Returns:

The standard tabular envelope, trimmed to the effective limit.

Raises:

• SqlExecutionError – When ClickHouse rejects the statement (sanitized error code line, without host, DSN or stack trace).

• SystemError – When the backend is unreachable; the message never carries the URL.

Return type:

SqlQueryResult