ClickhouseClient
ClickHouse driver for Effect SQL, backed by @clickhouse/client.
This module provides both the ClickHouse-specific ClickhouseClient service and the generic Client.SqlClient service. make creates a scoped client, checks the connection with SELECT 1, maps ClickHouse errors to SqlError, and aborts in-flight queries when interrupted. The ClickHouse-specific service adds typed parameters, command execution, insert queries, query id and settings helpers, a statement compiler, and direct or config-backed layers.
Constructors
Signature
declare function make(
options: ClickhouseClientConfig,
): Effect<ClickhouseClient, SqlError, Scope | Reactivity>;makeCompiler
Creates the SQL statement compiler for ClickHouse, emitting typed {pN: Type} placeholders and escaping identifiers with an optional query name transform.
Signature
declare function makeCompiler(transform?: (_: string) => string): Compiler;Layers
Provides both ClickhouseClient and generic SqlClient services from a ClickHouse client configuration.
Signature
declare function layer(
config: ClickhouseClientConfig,
): Layer<SqlClient | ClickhouseClient, SqlError | ConfigError>;layerConfig
Provides both ClickhouseClient and generic SqlClient services from a Config-backed ClickHouse client configuration.
Signature
declare const layerConfig: (
config: Config.Wrap<ClickhouseClientConfig>,
) => Layer.Layer<ClickhouseClient | Client.SqlClient, Config.ConfigError | SqlError>;Models
ClickhouseClientConfig interface
Configuration for creating a ClickHouse client, combining @clickhouse/client options with optional span attributes and query/result name transforms.
Signature
interface ClickhouseClientConfig extends unknown {
readonly spanAttributes?: Record<string, unknown>;
readonly transformQueryNames?: (str: string) => string;
readonly transformResultNames?: (str: string) => string;
}ClickhouseCustom type
Custom SQL fragment type used for ClickHouse typed parameters created by ClickhouseClient.param.
Signature
type ClickhouseCustom = ClickhouseParam;Services
ClickhouseClient
Service tag for the active ClickHouse SQL client.
When to use
Use to access or provide a ClickHouse SQL client through the Effect context.
Signature
declare const ClickhouseClient: Service<ClickhouseClient, ClickhouseClient>;ClickhouseClient interface
ClickHouse-specific SqlClient extension with access to its configuration, typed parameter fragments, command-mode execution, insert queries, and per-effect query ID and ClickHouse settings.
Signature
interface ClickhouseClient extends SqlClient {
<A extends object = Row>(strings: TemplateStringsArray, ...args: Array<any>): Statement<A>;
(value: string): Identifier;
readonly "~@effect/sql-clickhouse/ClickhouseClient": "~@effect/sql-clickhouse/ClickhouseClient";
readonly asCommand: <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
readonly config: ClickhouseClientConfig;
readonly insertQuery: <T = unknown>(options: {
readonly format?: any;
readonly table: string;
readonly values: InsertValues<Readable, T>;
}) => Effect<InsertResult, SqlError>;
readonly param: (dataType: string, value: unknown) => Fragment;
readonly withClickhouseSettings: {
(settings: any): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(effect: Effect<A, E, R>, settings: any): Effect<A, E, R>;
};
readonly withQueryId: {
(queryId: string): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(effect: Effect<A, E, R>, queryId: string): Effect<A, E, R>;
};
}ClickhouseSettings
Fiber reference containing ClickHouse settings to attach to queries, commands, and inserts.
Signature
declare const ClickhouseSettings: Context.Reference<
NonNullable<Clickhouse.BaseQueryParams["clickhouse_settings"]>
>;ClientMethod
Fiber reference read by the low-level ClickHouse connection to choose query or command execution for statements; defaults to query.
Signature
declare const ClientMethod: Reference<"query" | "command" | "insert">;Fiber reference for the ClickHouse query_id applied to queries and inserts; a random UUID is generated when no query ID is set.
Signature
declare const QueryId: Reference<string | undefined>;
Creates a scoped
ClickhouseClient, verifies connectivity withSELECT 1, closes the underlying client when the scope ends, maps ClickHouse failures toSqlError, and aborts plus kills in-flight queries when interrupted.