# @clickhouse/client

> Official JS client for ClickHouse DB - Node.js implementation

Latest version **1.23.1** (published 2026-07-07) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @clickhouse/client
pnpm add @clickhouse/client
yarn add @clickhouse/client
bun add @clickhouse/client
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.23.1 |
| Published | 2026-07-07 |
| First published | 2022-09-15 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 331 |
| Maintainers | mikhail.shustov-clickhouse, michael.anastasakis, 4b819b88c84b, santrancisco, hoorayimhelping, tresleches, vineethasok |
| Keywords | clickhouse, sql, client |

## Links

- npm: https://www.npmjs.com/package/@clickhouse/client
- Repository: https://github.com/ClickHouse/clickhouse-js
- Homepage: https://clickhouse.com
- Issues: https://github.com/ClickHouse/clickhouse-js/issues
- npm.io page: https://npm.io/package/@clickhouse/client

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 1.23.1 (latest) — 2026-07-07
- 1.24.0-head.443b2f0.1 (head) — 2026-07-16
- 0.100.1 (faster_exception_detection) — 2026-01-12
- 1.23.1-head.f67717b.1 — 2026-07-07
- 1.23.0-head.71b2e8a.1 — 2026-07-02
- 1.23.0 — 2026-06-29
- 1.23.0-head.70ad405.1 — 2026-06-29
- 1.23.0-head.dbc2960.1 — 2026-06-27
- 1.23.0-head.287977a.1 — 2026-06-27
- 1.23.0-head.fae5998.1 — 2026-06-25
- 1.23.0-head.b25cda1.1 — 2026-06-24
- 1.23.0-head.c8dc8d8.1 — 2026-06-22
- 1.22.0 — 2026-06-22
- 1.22.0-head.bb7d9d2.1 — 2026-06-18
- 1.21.0 — 2026-06-17
- … 119 more at https://npm.io/package/@clickhouse/client/versions

## README

# @clickhouse/client

Official Node.js client for [ClickHouse](https://clickhouse.com/), written
purely in TypeScript and thoroughly tested against actual ClickHouse versions.

It is built on top of the Node.js [HTTP](https://nodejs.org/api/http.html) and
[Stream](https://nodejs.org/api/stream.html) 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`](https://www.npmjs.com/package/@clickhouse/client-web).

## Installation

```sh
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](https://github.com/nodejs/release#readme)
Node.js releases.

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

If using TypeScript, version
[4.5](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html)
or above is required to enable
[inline import and export syntax](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names).

## 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

```ts
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](https://github.com/ClickHouse/clickhouse-js/tree/main/examples).

## Documentation

See the [ClickHouse website](https://clickhouse.com/docs/integrations/javascript)
for the full documentation.

## Changelog

See [`CHANGELOG.md`](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-node/CHANGELOG.md).

## Contact us

If you have any questions or need help, feel free to reach out to us in the
[Community Slack](https://clickhouse.com/slack) (`#clickhouse-js` channel) or
via [GitHub issues](https://github.com/ClickHouse/clickhouse-js/issues).

## License

[Apache 2.0](https://github.com/ClickHouse/clickhouse-js/blob/main/LICENSE)

---
_Source: https://npm.io/package/@clickhouse/client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._