ClickHouse JS

The official JS client for connecting to ClickHouse. The client is written in TypeScript and provides typings for the client public API.

It has zero dependencies, is optimized for maximum performance, and is tested with various ClickHouse versions and configurations (on-premise single node, on-premise cluster, and ClickHouse Cloud).

There are two different versions of the client available for different environments:

• @clickhouse/client - Node.js only
• @clickhouse/client-web - browsers (Chrome/Firefox), Cloudflare workers

When using TypeScript, make sure it is at least version 4.5, which enables inline import and export syntax.

The client source code is available in the ClickHouse-JS GitHub repository.

Environment requirements (node.js)​

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

As soon as a Node.js version approaches End-Of-Life, the client drops support for it as it is considered outdated and insecure.

Current Node.js versions support:

Environment requirements (web)​

The web version of the client is officially tested with the latest Chrome/Firefox browsers and can be used as a dependency in, for example, React/Vue/Angular applications, or Cloudflare workers.

Installation​

To install the latest stable Node.js client version, run:

npm i @clickhouse/client

Web version installation:

npm i @clickhouse/client-web

Compatibility with ClickHouse​

Likely, the client will work with the older versions, too; however, this is best-effort support and is not guaranteed. If you have a ClickHouse version older than 23.3, please refer to ClickHouse security policy and consider upgrading.

Examples​

We aim to cover various scenarios of client usage with the examples in the client repository.

The overview is available in the examples README.

If something is unclear or missing from the examples or from the following documentation, feel free to contact us.

Client API​

Most of the examples should be compatible with both Node.js and web versions of the client, unless explicitly stated otherwise.

Creating a client instance​

You can create as many client instances as necessary with the createClient factory:

import { createClient } from '@clickhouse/client' // or '@clickhouse/client-web'

const client = createClient({
  /* configuration */
})

If your environment doesn't support ESM modules, you can use CJS syntax instead:

const { createClient } = require('@clickhouse/client');

const client = createClient({
  /* configuration */
})

A client instance can be pre-configured during instantiation.

Configuration​

When creating a client instance, the following connection settings can be adjusted:

Node.js-specific configuration parameters​

URL configuration​

It is possible to configure most of the client instance parameters with a URL. The URL format is http[s]://[username:password@]hostname:port[/database][?param1=value1&param2=value2]. In almost every case, the name of a particular parameter reflects its path in the config options interface, with a few exceptions. The following parameters are supported:

• (1) For booleans, valid values will be true/1 and false/0.
• (2) Any parameter prefixed with clickhouse_setting_ or ch_ will have this prefix removed and the rest added to client's clickhouse_settings. For example, ?ch_async_insert=1&ch_wait_for_async_insert=1 will be the same as:

createClient({
  clickhouse_settings: {
    async_insert: 1,
    wait_for_async_insert: 1,
  },
})

Note: boolean values for clickhouse_settings should be passed as 1/0 in the URL.

• (3) Similar to (2), but for http_header configuration. For example, ?http_header_x-clickhouse-auth=foobar will be an equivalent of:

createClient({
  http_headers: {
    'x-clickhouse-auth': 'foobar',
  },
})

Connecting​

Gather your connection details​

To connect to ClickHouse with HTTP(S) you need this information:

• The HOST and PORT: typically, the port is 8443 when using TLS or 8123 when not using TLS.

• The DATABASE NAME: out of the box, there is a database named default, use the name of the database that you want to connect to.

• The USERNAME and PASSWORD: out of the box, the username is default. Use the username appropriate for your use case.

The details for your ClickHouse Cloud service are available in the ClickHouse Cloud console. Select the service that you will connect to and click Connect: