@clickhouse/client

@clickhouse/client is the official Node.js client for ClickHouse, the open-source column-oriented database built for real-time analytics. Written entirely in TypeScript with zero external runtime dependencies, it wraps Node’s built-in HTTP and Stream APIs to give applications a typed, promise-based interface for running queries, inserts, and commands against a ClickHouse server or ClickHouse Cloud.

The client is one of four packages published from the ClickHouse/clickhouse-js monorepo: @clickhouse/client (this package, Node.js-specific), @clickhouse/client-web (Fetch/Web Streams-based, for browsers and edge runtimes like Cloudflare Workers), @clickhouse/client-common (shared types and the base client framework both platform packages extend), and @clickhouse/datatype-parser (a standalone parser for ClickHouse’s column type strings). @clickhouse/client is the one most Node.js backends should install directly.

It supports streaming reads and writes for large result sets, a wide range of ClickHouse’s native data formats (JSONEachRow, CSV, native RowBinary, and more), configurable compression, session and query-level ClickHouse settings, JWT and basic auth, and OpenTelemetry-compatible tracing hooks. The project maintains an extensive integration test suite that runs against real ClickHouse instances, plus a dedicated ‘oss-dependents’ test suite that exercises the client the same way real downstream open-source projects (Umami, Cube, Nango, and others) actually use it in production, catching regressions before they reach consumers.

What You Get

• A createClient() factory returning a typed NodeClickHouseClient with query, insert, exec, and command methods for every interaction pattern with ClickHouse.
• Native streaming support in both directions: Stream.Readable result sets for large selects and streamable input values for inserts, so payloads never need to be fully buffered in memory.
• Support for ClickHouse’s full range of data formats (JSON variants, CSV/TSV, native RowBinary via the companion parser) with typed helpers like resultSet.json() and resultSet.text().
• Built-in connection-level features: gzip request/response compression, keep-alive HTTP agent pooling, JWT and basic auth, and per-query ClickHouse settings typed against ClickHouseSettings.
• OpenTelemetry-shaped tracing primitives (ClickHouseTracer, ClickHouseSpan) so query spans can be wired into an existing observability pipeline without a separate instrumentation package.

Common Use Cases

• Backing a real-time analytics dashboard or product-analytics tool (as done by projects like Umami) with sub-second aggregate queries over large event tables.
• Bulk-loading application or log events into ClickHouse via streamed inserts, without holding entire batches in process memory.
• Building an internal BI/reporting service that runs parameterized SQL against ClickHouse and streams JSON results back to a frontend.
• Integrating ClickHouse as the storage/query layer inside a larger open-source tool (data pipeline platforms, log analytics, feature stores) via a stable, versioned client instead of hand-rolled HTTP calls.

Under The Hood

Architecture The package is a thin Node.js-specific layer over a shared core: packages/client-node/src/client.ts defines NodeClickHouseClient, which extends the base ClickHouseClient exported from @clickhouse/client-common (re-exported locally under ./common/index), and createClient() simply instantiates that base class with a Node-specific impl object (NodeConfigImpl) supplying HTTP connection factories from src/connection/ (node_http_connection.ts, node_https_connection.ts, node_custom_agent_connection.ts, socket_pool.ts). This mirrors the equivalent client-web package, which supplies a Fetch/Web-Streams impl instead — so platform differences are isolated to the connection layer while query building, settings typing, result parsing, and error handling live once in client-common. The createClient() factory also accepts an injected connection, overriding the default HTTP factory entirely, which the code notes exists for an experimental chDB integration — evidence the connection abstraction is a deliberate seam, not an implementation detail leaking through.

Tech Stack Written entirely in TypeScript (Node 20+ required) with an empty dependencies field in package.json — the published client has zero runtime dependencies, relying only on Node’s built-in http/https and stream modules for I/O. The monorepo root uses npm workspaces across packages/*, with typescript, eslint + typescript-eslint, prettier, and vitest (plus @vitest/coverage-v8/istanbul) as the shared toolchain; devDependencies for the node package add only simdjson for benchmarking. Builds run through plain tsc; the browser-facing sibling package additionally pulls in playwright and @vitest/browser-playwright for cross-browser testing.

Code Quality Testing is extensive: 136 *.test.ts files across the monorepo (76 under client-node alone), split into unit tests (test:unit, mockable via CLICKHOUSE_TEST_SKIP_INIT), integration tests that run against real ClickHouse instances (test:integration, :tls, :local_cluster, :cloud), and a distinctive test:oss-dependents suite (__tests__/oss-dependents/) that exercises the client the way real downstream projects (Umami, Cube, Nango, Firecrawl, Daytona, and others) actually use it, catching breaking changes before they reach consumers. CI runs a dedicated workflow per test category (tests-node.yml, tests-web.yml, tests-bun.yml, tests-oss-dependents.yml, tests-dist.yml), plus husky + lint-staged pre-commit hooks, strict ESLint (--max-warnings=0), and a Scorecard security badge. Public APIs are fully typed, with generic DataFormat-parameterized return types (QueryResult<Format>) that narrow at compile time rather than relying on runtime checks.

API Design The public surface is intentionally small: createClient() plus a handful of methods (query, insert, exec, command) cover the entire interaction model, and format-specific typing (resultSet.json() vs .text()) is inferred from the format option passed at the call site rather than requiring separate methods per format. The README documents an explicit client-version-to-ClickHouse-version compatibility table, reducing upgrade guesswork, and values re-exported from the shared client-common package are re-bound locally specifically so @deprecated JSDoc tags don’t leak onto the recommended import path — a level of API surface curation that goes beyond typical wrapper packages.