ClickHouse JS client

About

Official JS client for ClickHouse, written purely in TypeScript, thoroughly tested with actual ClickHouse versions.

The client has zero external dependencies and is optimized for maximum performance.

The repository consists of four packages:

• @clickhouse/client - a version of the client designed for Node.js platform only. It is built on top of HTTP

• @clickhouse/client-web - a version of the client built on top of Fetch

• @clickhouse/client-common - shared common types and the base framework for building a custom client implementation.
• @clickhouse/rowbinary - a library for reading (and soon writing) ClickHouse RowBinary format.

Installation

Node.js client:

npm i @clickhouse/client

Web client (browsers, Cloudflare workers):

npm i @clickhouse/client-web

Environment requirements

Node.js

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

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

TypeScript

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"; // or '@clickhouse/client-web'
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

Each package keeps its own changelog:

• @clickhouse/client — packages/client-node/CHANGELOG.md
• @clickhouse/client-web — packages/client-web/CHANGELOG.md
• @clickhouse/client-common (deprecated) — packages/client-common/CHANGELOG.md
• @clickhouse/datatype-parser — packages/datatype-parser/CHANGELOG.md
• @clickhouse/rowbinary — skills/clickhouse-js-node-rowbinary/CHANGELOG.md

AI Agent Skills

This repository contains agent skills for working with the client:

• clickhouse-js-node-troubleshooting — troubleshooting playbook for the Node.js client.

# per project
npx skills add ClickHouse/clickhouse-js
globally
npx skills add ClickHouse/clickhouse-js -g

Or ask your agent to install it for you:

install agent skills from ClickHouse/clickhouse-js

Usage examples

We have a wide range of examples, aiming to cover various scenarios of client usage. The overview is available in the examples README.

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.

Contributing

Check out our contributing guide.

If you'd like to build a client for an alternative runtime (such as Bun or Cloudflare Workers) or an alternative protocol (such as the native ClickHouse protocol or gRPC over a proxy), see Building specialized clients for alternative runtimes and protocols.