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.