1.2.0 (Node.js only)

New features

• (Experimental) Added an option to provide a custom HTTP Agent in the client configuration via the http_agent option (#283, related: #278). The following conditions apply if a custom HTTP Agent is provided:

  • The max_open_connections and tls options will have no effect and will be ignored by the client, as those are part of the underlying HTTP Agent configuration.
  • keep_alive.enabled will only regulate the default value of the Connection header (true -> Connection: keep-alive, false -> Connection: close).
  • While the idle socket management will still work, it is now possible to disable it completely by setting the keep_alive.idle_socket_ttl value to 0.

• (Experimental) Added a new client configuration option: set_basic_auth_header, which controls whether the Authorization header should be set for every outgoing HTTP request (enabled by default). One of the possible scenarios when it is necessary to disable this header is when a custom HTTPS agent is used, and the server requires TLS with certificates. For example:

  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,
  })

NB: It is currently not possible to set the set_basic_auth_header option via the URL params.

See the doc entry regarding custom HTTP(s) Agent usage with code samples.

If you have feedback on these experimental features, please let us know by creating an issue in the repository or send a message in the Community Slack (#clickhouse-js channel).