ClickHouse JS

#### Creating a client instance[​](#creating-a-client-instance "Direct link to 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](/docs/integrations/javascript#configuration) during instantiation.

#### Configuration[​](#configuration "Direct link to Configuration")

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

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Setting Description Default Value See Also|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **url**?: string A ClickHouse instance URL. `http://localhost:8123` [URL configuration docs](/docs/integrations/javascript#url-configuration)| **pathname**?: string An optional pathname to add to the ClickHouse URL after it is parsed by the client. `''` [Proxy with a pathname docs](/docs/integrations/javascript#proxy-with-a-pathname)| **request\_timeout**?: number The request timeout in milliseconds. `30_000` -|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **compression**?: `{ **response**?: boolean; **request**?: boolean }` Enable compression. - [Compression docs](/docs/integrations/javascript#compression)| **username**?: string The name of the user on whose behalf requests are made. `default` -|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **password**?: string The user password. `''` -|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **application**?: string The name of the application using the Node.js client. `clickhouse-js` -|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **database**?: string The database name to use. `default` -|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **clickhouse\_settings**?: ClickHouseSettings ClickHouse settings to apply to all requests. `{}` -|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **log**?: `{ **LoggerClass**?: Logger, **level**?: ClickHouseLogLevel }` Internal client logs configuration. - [Logging docs](/docs/integrations/javascript#logging-nodejs-only)| **session\_id**?: string Optional ClickHouse Session ID to send with every request. - -|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **keep\_alive**?: `{ **enabled**?: boolean }` Enabled by default in both Node.js and Web versions. - -|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | **http\_headers**?: `Record<string, string>` Additional HTTP headers for outgoing ClickHouse requests. - [Reverse proxy with authentication docs](/docs/integrations/javascript#reverse-proxy-with-authentication)| **roles**?: string | string[] ClickHouse role names to attach to the outgoing requests. - [Using roles with the HTTP interface](/docs/interfaces/http#setting-role-with-query-parameters) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

#### Node.js-specific configuration parameters[​](#nodejs-specific-configuration-parameters "Direct link to Node.js-specific configuration parameters")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Setting Description Default Value See Also|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **max\_open\_connections**?: number A maximum number of connected sockets to allow per host. `10` -|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | **tls**?: `{ **ca_cert**: Buffer, **cert**?: Buffer, **key**?: Buffer }` Configure TLS certificates. - [TLS docs](/docs/integrations/javascript#tls-certificates-nodejs-only)| **keep\_alive**?: `{ **enabled**?: boolean, **idle_socket_ttl**?: number }` - - [Keep Alive docs](/docs/integrations/javascript#keep-alive-configuration-nodejs-only)| **http\_agent**?: http.Agent | https.Agent   Experimental feature. [Learn more.](/docs/beta-and-experimental-features#experimental-features)  Custom HTTP agent for the client. - [HTTP agent docs](/docs/integrations/javascript#custom-httphttps-agent-experimental-nodejs-only)| **set\_basic\_auth\_header**?: boolean   Experimental feature. [Learn more.](/docs/beta-and-experimental-features#experimental-features)  Set the `Authorization` header with basic auth credentials. `true` [this setting usage in the HTTP agent docs](/docs/integrations/javascript#custom-httphttps-agent-experimental-nodejs-only) | | | | | | | | | | | | | | | | | | | | | | | |

### URL configuration[​](#url-configuration "Direct link to URL configuration")

References

URL configuration will *always* overwrite the hardcoded values and a warning will be logged in this case.

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: