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 three packages:
@clickhouse/client- a version of the client designed for Node.js platform only. It is built on top of HTTP and Stream APIs; supports streaming for both selects and inserts.@clickhouse/client-web- a version of the client built on top of Fetch and Web Streams APIs; supports streaming for selects. Compatible with Chrome/Firefox browsers and Cloudflare workers.@clickhouse/client-common- shared common types and the base framework for building a custom client implementation.
Node.js client:
npm i @clickhouse/clientWeb client (browsers, Cloudflare workers):
npm i @clickhouse/client-webNode.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? |
|---|---|
| 24.x | ✔ |
| 22.x | ✔ |
| 20.x | ✔ |
| 18.x | Best effort |
If using TypeScript, version 4.5 or above is required to enable inline import and export syntax.
| 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.
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.
See the ClickHouse website for the full documentation.
We have a wide range of examples, aiming to cover various scenarios of client usage. The overview is available in the examples README.
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.
Check out our contributing guide.