GitHub

API reference for client.

The ClickHouse client (Effect's @effect/sql-clickhouse ClickhouseClient): an SqlClient over ClickHouse's HTTP interface, with typed parameters (param), commands (as_command), inserts in any format (insert_query) and per-effect query ids and settings.

make checks the server with /ping (within five seconds). Statements compile to {p1: Type} placeholders, the type inferred from the value (params.type_of) unless param names it, and "quoted" names::

program.pipe(fx.provide(clickhouse.layer(clickhouse.ClickhouseClientConfig(url=...))))

A statement runs as a query with FORMAT JSON appended, which a statement with data (INSERT ... VALUES) does not accept: run those with as_command or use insert_query.

Re-exports

Values

AttributeTypeDescription
is_clickhouse_param(object) -> TypeIs[Custom[Any, Any, Any, Any]]
CONNECT_TIMEOUTLiteral['5 seconds'] = '5 seconds'

How long make waits for /ping, in seconds.

Types

TypeDefinitionDescription
ClickhouseParamtype ClickhouseParam = Custom[str, str, object, None]

A parameter bound as a named ClickHouse type (param).

Classes

Functions

make_compiler

make_compiler(transform=None) -> Compiler

ClickHouse's compiler: {p1: Type} placeholders and "quoted" names (renamed with transform unless a statement runs without transforms).

ParameterTypeDescription
transformCallable[[str], str] | None = None

Returns Compiler

def make_compiler(transform: Callable[[str], str] | None = None) -> Compiler:
    """ClickHouse's compiler: ``{p1: Type}`` placeholders and ``"quoted"``
    names (renamed with ``transform`` unless a statement runs without
    transforms)."""

    def on_identifier(value: str, without_transform: bool) -> str:
        if transform is None or without_transform:
            return _escape(value)
        return _escape(transform(value))

    return make_statement_compiler(
        dialect="clickhouse",
        placeholder=lambda index, value: f"{{p{index}: {_placeholder_type(value)}}}",
        on_identifier=on_identifier,
        on_record_update=_nothing,
        on_custom=_on_custom,
    )

make

make(config) -> Effect[ClickhouseClientService, SqlError, Scope | Reactivity]

A client on config's server; the HTTP client it creates closes with the scope.

ParameterTypeDescription
configClickhouseClientConfig

Returns Effect[ClickhouseClientService, SqlError, Scope | Reactivity]

def make(
    config: ClickhouseClientConfig,
) -> Effect[ClickhouseClientService, SqlError, Scope | Reactivity]:
    """A client on ``config``'s server; the HTTP client it creates closes
    with the scope."""
    compiler = make_compiler(config.transform_query_names)
    transform_rows = (
        None
        if config.transform_result_names is None
        else default_transforms(config.transform_result_names).array
    )
    span_attributes: list[tuple[str, object]] = [
        *config.span_attributes.items(),
        ("db.system.name", "clickhouse"),
        ("db.namespace", config.connection.database),
    ]

    def build(http: Any) -> Effect[ClickhouseClientService, SqlError, Reactivity]:
        driver = ClickhouseDriver(http, config.connection)
        connected = (
            driver.ping()
            .map_error(catch("ClickhouseClient: Failed to connect", "connect", "connection"))
            .timeout_or_else(CONNECT_TIMEOUT, _connect_timed_out)
        )
        connection: Connection = ClickhouseConnection(driver)
        client = make_sql_client(
            driver="clickhouse",
            acquirer=succeed(connection),
            compiler=compiler,
            span_attributes=span_attributes,
            begin_transaction="BEGIN TRANSACTION",
            transform_rows=transform_rows,
        )

        def finish(c: SqlClientService) -> ClickhouseClientService:
            return ClickhouseClientService(config=config, client=driver, **c.fields())

        return connected.and_then(client.map(finish))

    return _config_warnings(config).and_then(_http_client(config).flat_map(build))

layer_from

layer_from[E](acquire) -> Layer[ClickhouseClient | SqlClient, E]

Provides the client acquire makes as ClickhouseClient and SqlClient, with its own Reactivity.

ParameterTypeDescription
acquireEffect[ClickhouseClientService, E, Scope | Reactivity]

Returns Layer[ClickhouseClient | SqlClient, E]

def layer_from[E](
    acquire: Effect[ClickhouseClientService, E, Scope | Reactivity],
) -> Layer[ClickhouseClient | SqlClient, E]:
    """Provides the client ``acquire`` makes as ``ClickhouseClient`` and
    ``SqlClient``, with its own ``Reactivity``."""
    require_effect(acquire, "acquire")
    return layer_effect_context(acquire.map(_contexts)).pipe(provide(reactivity_layer))

layer

layer(config) -> Layer[ClickhouseClient | SqlClient, SqlError]

Provides a client (make).

ParameterTypeDescription
configClickhouseClientConfig

Returns Layer[ClickhouseClient | SqlClient, SqlError]

def layer(config: ClickhouseClientConfig) -> Layer[ClickhouseClient | SqlClient, SqlError]:
    """Provides a client (``make``)."""
    return layer_from(make(config))

layer_config

layer_config(config) -> Layer[ClickhouseClient | SqlClient, ConfigError | SqlError]

layer with the config read from the ConfigProvider: a Config of the whole config, or a mapping from field names to their Config (Effect's Config.Wrap)::

clickhouse.layer_config({
    "url": fx.config.string("CLICKHOUSE_URL"),
    "password": fx.config.redacted("CLICKHOUSE_PASSWORD"),
})
ParameterTypeDescription
configConfig[ClickhouseClientConfig] | Mapping[str, Any]

Returns Layer[ClickhouseClient | SqlClient, ConfigError | SqlError]

def layer_config(
    config: Config[ClickhouseClientConfig] | Mapping[str, Any],
) -> Layer[ClickhouseClient | SqlClient, ConfigError | SqlError]:
    """``layer`` with the config read from the ``ConfigProvider``: a
    ``Config`` of the whole config, or a mapping from field names to their
    ``Config`` (Effect's ``Config.Wrap``)::

        clickhouse.layer_config({
            "url": fx.config.string("CLICKHOUSE_URL"),
            "password": fx.config.redacted("CLICKHOUSE_PASSWORD"),
        })
    """
    read: Effect[ClickhouseClientConfig, ConfigError] = (
        config
        if isinstance(config, Config)
        else unwrap(config).map(lambda fields: ClickhouseClientConfig(**fields))
    )
    return layer_from(read.flat_map(make))