clickhouse-sdk-patterns

# ClickHouse SDK Patterns ## Overview Production patterns for `@clickhouse/client` — typed queries, streaming inserts, error handling, and connection lifecycle management. ## Prerequisites - `@clickhouse/client` installed (see `clickhouse-install-auth`) - Familiarity with async/await and Node.js streams ## Instructions ### Pattern 1: Typed Query Helper ```typescript import { createClient } from '@clickhouse/client'; const client = createClient({ url: process.env.CLICKHOUSE_HOST!, username: process.env.CLICKHOUSE_USER ?? 'default', password: process.env.CLICKHOUSE_PASSWORD ?? '', }); // Generic typed query — returns parsed JSON rows async function query<T>(sql: string, params?: Record<string, unknown>): Promise<T[]> { const rs = await client.query({ query: sql, query_params: params, format: 'JSONEachRow', }); return rs.json<T>(); } // Usage interface EventCount { event_type: string; cnt: string; // ClickHouse JSON returns numbers as strings } const rows = await query<EventCount>( 'SELECT event_type, count() AS cnt FROM events WHERE user_id = {user_id:UInt64} GROUP BY event_type', { user_id: 42 } ); ``` **Note on parameterized queries:** ClickHouse uses `{name:Type}` syntax for parameters, not `$1` or `?`. Always use typed parameters to prevent SQL injection. ### Pattern 2: Streaming Insert (Backpressure-Safe) ```typescript import { createClient } from '@clickhouse/client'; import { Readable } from 'stream'; // For large inserts, ...