Agent skill · software engineering · jeremylongshore
clickhouse-sdk-patterns
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".
Why this skill is useful
Provides specific patterns and code snippets for integrating with ClickHouse that the AI wouldn't reliably generate on its own.
What it needs
Requires @clickhouse/client, node installed locally. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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 CLICKHOUSEHOST / CLICKHOUSEUSER / CLICKHOUSEPASSWORD 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 maxthreads, maxmemoryusage, maxexecutiontime, and maxresultrows for heavy queries. Skeleton: Typed Query Helper Note on parameterized queries: ClickHouse uses {name:Type} syntax for parameters, not $1 or ?. Always use typed parameters to prevent SQL injection. Output Applying these patterns produces: A single reusable client instance plus a generic query<T> helper that returns typed, parsed rows. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/clickhouse-sdk-patterns