ClickHouse JS

Using a custom HTTPS Agent with mutual TLS:

```
const agent = new https.Agent({
  keepAlive: true,
  keepAliveMsecs: 2500,
  maxSockets: 10,
  maxFreeSockets: 10,
  ca: fs.readFileSync('./ca.crt'),
  cert: fs.readFileSync('./client.crt'),
  key: fs.readFileSync('./client.key'),
})
const client = createClient({
  url: 'https://myserver:8443',
  http_agent: agent,
  // With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the headers should be provided manually
  http_headers: {
    'X-ClickHouse-User': 'username',
    'X-ClickHouse-Key': 'password',
    'X-ClickHouse-SSL-Certificate-Auth': 'on',
  },
  // Important: authorization header conflicts with the TLS headers; disable it.
  set_basic_auth_header: false,
})
```

With certificates *and* a custom *HTTPS* Agent, it is likely necessary to disable the default authorization header via the `set_basic_auth_header` setting (introduced in 1.2.0), as it conflicts with the TLS headers. All the TLS headers should be provided manually.

## Known limitations (Node.js/web)[​](#known-limitations-nodejsweb "Direct link to Known limitations (Node.js/web)")

- There are no data mappers for the result sets, so only language primitives are used. Certain data type mappers are planned with [RowBinary format support](https://github.com/ClickHouse/clickhouse-js/issues/216).
- There are some [Decimal\* and Date\* / DateTime\* data types caveats](/docs/integrations/javascript#datedate32-types-caveats).
- When using JSON\* family formats, numbers larger than Int32 are represented as strings, as Int64+ types maximum values are larger than `Number.MAX_SAFE_INTEGER`. See the [Integral types](/docs/integrations/javascript#integral-types-int64-int128-int256-uint64-uint128-uint256) section for more details.

## Known limitations (web)[​](#known-limitations-web "Direct link to Known limitations (web)")

- Streaming for select queries works, but it is disabled for inserts (on the type level as well).
- Request compression is disabled and configuration is ignored. Response compression works.
- No logging support yet.

## Tips for performance optimizations[​](#tips-for-performance-optimizations "Direct link to Tips for performance optimizations")

- To reduce application memory consumption, consider using streams for large inserts (e.g. from files) and selects when applicable. For event listeners and similar use cases, [async inserts](/docs/optimize/asynchronous-inserts) could be another good option, allowing to minimize, or even completely avoid batching on the client side. Async insert examples are available in the [client repository](https://github.com/ClickHouse/clickhouse-js/tree/main/examples), with `async_insert_` as the file name prefix.
- The client doesn't enable request or response compression by default. However, when selecting or inserting large datasets, you could consider enabling it via `ClickHouseClientConfigOptions.compression` (either for just `request` or `response`, or both).
- Compression has significant performance penalty. Enabling it for `request` or `response` will negatively impact the speed of selects or inserts, respectively, but will reduce the amount of network traffic transferred by the application.

## Contact us[​](#contact-us "Direct link to 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).

- [Environment requirements (node.js)](#environment-requirements-nodejs)- [Environment requirements (web)](#environment-requirements-web)- [Installation](#installation)- [Compatibility with ClickHouse](#compatibility-with-clickhouse)- [Examples](#examples)
          - [Client API](#client-api)- [URL configuration](#url-configuration)- [Connecting](#connecting)- [Query ID](#query-id)- [Base parameters for all client methods](#base-parameters-for-all-client-methods)- [Query method](#query-method)- [Insert method](#insert-method)- [Command method](#command-method)- [Exec method](#exec-method)- [Ping](#ping)- [Close (Node.js only)](#close-nodejs-only)- [Streaming files (Node.js only)](#streaming-files-nodejs-only)- [Supported data formats](#supported-data-formats)- [Supported ClickHouse data types](#supported-clickhouse-data-types)
                - [Date/Date32 types caveats](#datedate32-types-caveats)- [Decimal\* types caveats](#decimal-types-caveats)- [Integral types: Int64, Int128, Int256, UInt64, UInt128, UInt256](#integral-types-int64-int128-int256-uint64-uint128-uint256)- [ClickHouse settings](#clickhouse-settings)- [Advanced topics](#advanced-topics)
                    - [Queries with parameters](#queries-with-parameters)- [Compression](#compression)- [Logging (Node.js only)](#logging-nodejs-only)- [TLS certificates (Node.js only)](#tls-certificates-nodejs-only)- [Keep-alive configuration (Node.js only)](#keep-alive-configuration-nodejs-only)- [Read-only users](#read-only-users)- [Proxy with a pathname](#proxy-with-a-pathname)- [Reverse proxy with authentication](#reverse-proxy-with-authentication)- [Custom HTTP/HTTPS agent (experimental, Node.js only)](#custom-httphttps-agent-experimental-nodejs-only)- [Known limitations (Node.js/web)](#known-limitations-nodejsweb)- [Known limitations (web)](#known-limitations-web)- [Tips for performance optimizations](#tips-for-performance-optimizations)- [Contact us](#contact-us)

Was this page helpful?