@clickhouse/client

Official Node.js client for ClickHouse, written purely in TypeScript and thoroughly tested against actual ClickHouse versions.

It is built on top of the Node.js HTTP and Stream APIs and supports streaming for both selects and inserts. The client has zero external dependencies and is optimized for maximum performance.

Looking for a browser / edge runtime (Cloudflare Workers, etc.) instead? Use @clickhouse/client-web.

Installation

npm i @clickhouse/client

Environment requirements

Node.js must be available in the environment to run the client. The client is compatible with all the maintained Node.js releases.

| Node.js version | Supported? | | --------------- | ---------- | | 26.x | ✔ | | 24.x | ✔ | | 22.x | ✔ | | 20.x | ✔ |

If using TypeScript, version 4.5 or above is required to enable inline import and export syntax.

Compatibility with ClickHouse

| Client version | ClickHouse | | -------------- | ---------- | | 1.12.0+ | 24.8+ |

The client may work with older versions too; however, this is best-effort support and is not guaranteed.

Quick start

import { createClient } from "@clickhouse/client";

const client = createClient({
  url: process.env.CLICKHOUSE_URL ?? "http://localhost:8123",
  username: process.env.CLICKHOUSE_USER ?? "default",
  password: process.env.CLICKHOUSE_PASSWORD ?? "",
});

const resultSet = await client.query({
  query: "SELECT * FROM system.tables",
  format: "JSONEachRow",
});

const tables = await resultSet.json();
console.log(tables);

await client.close();

See more examples in the examples directory.

Documentation

See the ClickHouse website for the full documentation.

Changelog

See CHANGELOG.md.

Contact us

If you have any questions or need help, feel free to reach out to us in the Community Slack (#clickhouse-js channel) or via GitHub issues.

License

Apache 2.0