clickhouse-sdk-patterns

name	clickhouse-sdk-patterns
description	Production-ready patterns for @clickhouse/client — streaming inserts, typed queries, error handling, and connection management. Use when building robust ClickHouse integrations, implementing streaming inserts or low-memory streaming reads, or establishing team coding standards. Trigger with "clickhouse SDK patterns", "clickhouse client patterns", "clickhouse best practices", "clickhouse streaming insert".
allowed-tools	Read
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","database","analytics","clickhouse","olap"]
compatibility	Designed for Claude Code

ClickHouse SDK Patterns

Overview

Production patterns for @clickhouse/client — typed queries, streaming inserts, error handling, and connection lifecycle management. Start from the typed query helper below, then drill into references/implementation.md for the streaming, batching, and lifecycle patterns.

Prerequisites

• @clickhouse/client installed and authenticated (see clickhouse-install-auth)
• Node.js 18+ with a CLICKHOUSE_HOST / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD env set
• Familiarity with async/await and Node.js streams (backpressure, drain, Readable)

Instructions

Apply the pattern that fits your workload. Steps 2–7 live in references/implementation.md with full, copy-pasteable code; the core typed-query skeleton stays here.

1. Typed query helper — the foundation every other pattern builds on. Define a generic query<T> wrapper that returns parsed rows (skeleton below).
2. Streaming insert (backpressure-safe) — stream large inserts through a Readable instead of buffering in memory; honor drain.
3. Batch insert with retry — chunk rows (default 10k) with exponential-backoff retries, returning { inserted, errors }.
4. Streaming SELECT (low memory) — consume large result sets as an AsyncGenerator so you never load the full set into RAM.
5. Error handling — distinguish server-side ClickHouseError (code + message) from network/client errors and normalize into a structured result.
6. Connection lifecycle — flush pending inserts on SIGTERM via client.close(); expose a ping()-based health check.
7. Per-query settings — override max_threads, max_memory_usage, max_execution_time, and max_result_rows for heavy queries.

Skeleton: Typed Query Helper

import { createClient } from ;

 client = ({
  : process..!,
  : process.. ?? ,
  : process.. ?? ,
});


  query<T>(: , ?: <, >): <T[]> {
   rs =  client.({
    : sql,
    : params,
    : ,
  });
   rs.<T>();
}