@clickhouse/client-web - npm Package Versions

1.3.0 (Common, Node.js, Web)

New features

• It is now possible to get the entire response headers object from the query/insert/command/exec methods. With query, you can access the ResultSet.response_headers property; other methods (insert/command/exec) return it as parts of their response objects as well. For example:

  const rs = await client.query({
    query: 'SELECT * FROM system.numbers LIMIT 1',
    format: 'JSONEachRow',
  })
  console.log(rs.response_headers['content-type'])
  

  This will print: application/x-ndjson; charset=UTF-8. It can be used in a similar way with the other methods.

Improvements

• Re-exported several constants from the @clickhouse/client-common package for convenience:

  • SupportedJSONFormats
  • SupportedRawFormats
  • StreamableFormats
  • StreamableJSONFormats
  • SingleDocumentJSONFormats
  • RecordsJSONFormats

1.2.0 (Node.js)

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 it is a 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 disables the Authorization header that is set by the client by default for every outgoing HTTP request. 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 authorization. For example:

  const agent = new https.Agent({
    ca: fs.readFileSync('./ca.crt'),
  })
  const client = createClient({
    url: 'https://server.clickhouseconnect.test: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': 'default',
      'X-ClickHouse-Key': '',
    },
    // 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.

If you have feedback on these experimental features, please let us know by creating an issue in the repository.

1.1.0 (Common, Node.js, Web)

New features

• Added an option to override the credentials for a particular query/command/exec/insert request via the BaseQueryParams.auth setting; when set, the credentials will be taken from there instead of the username/password provided during the client instantiation (#278).
• Added an option to override the session_id for a particular query/command/exec/insert request via the BaseQueryParams.session_id setting; when set, it will be used instead of the session id provided during the client instantiation (@holi0317, #271).

Bug fixes

• Fixed the incorrect ResponseJSON<T>.totals TypeScript type. Now it correctly matches the shape of the data (T, default = unknown) instead of the former Record<string, number> definition (#274).

1.0.2 (Common, Node.js, Web)

Bug fixes

• The command method now drains the response stream properly, as the previous implementation could cause the Keep-Alive socket to close after each request.
• Removed an unnecessary error log in the ResultSet.stream method if the request was aborted or the result set was closed (#263).

Improvements

• ResultSet.stream logs an error via the Logger instance, if the stream emits an error event instead of a simple console.error call.
• Minor adjustments to the DefaultLogger log messages formatting.
• Added missing rows_before_limit_at_least to the ResponseJSON type (@0237h, #267).

1.0.1 (Common, Node.js, Web)

Bug fixes

• Fixed the regression where the default HTTP/HTTPS port numbers (80/443) could not be used with the URL configuration (#258).

1.0.0 (Common, Node.js, Web)

Formal stable release milestone with a lot of improvements and some breaking changes.

Major new features overview:

• Advanced TypeScript support for query + ResultSet
• URL configuration

From now on, the client will follow the official semantic versioning guidelines.

Deprecated API

The following configuration parameters are marked as deprecated:

• host configuration parameter is deprecated; use url instead.
• additional_headers configuration parameter is deprecated; use http_headers instead.

The client will log a warning if any of these parameters are used. However, it is still allowed to use host instead of url and additional_headers instead of http_headers for now; this deprecation is not supposed to break the existing code.

These parameters will be removed in the next major release (2.0.0).

See "New features" section for more details.

0.3.1 (Common, Node.js, Web)

Bug fixes

• Fixed an issue where query parameters containing tabs or newline characters were not encoded properly.

0.3.0 (Node.js only)

This release primarily focuses on improving the Keep-Alive mechanism's reliability on the client side.

New features

• Idle sockets timeout rework; now, the client attaches internal timers to idling sockets, and forcefully removes them from the pool if it considers that a particular socket is idling for too long. The intention of this additional sockets housekeeping is to eliminate "Socket hang-up" errors that could previously still occur on certain configurations. Now, the client does not rely on KeepAlive agent when it comes to removing the idling sockets; in most cases, the server will not close the socket before the client does.

• There is a new keep_alive.idle_socket_ttl configuration parameter. The default value is 2500 (milliseconds), which is considered to be safe, as ClickHouse versions prior to 23.11 had keep_alive_timeout set to 3 seconds by default, and keep_alive.idle_socket_ttl is supposed to be slightly less than that to allow the client to remove the sockets that are about to expire before the server does so.

• Logging improvements: more internal logs on failing requests; all client methods except ping will log an error on failure now. A failed ping will log a warning, since the underlying error is returned as a part of its result. Client logging still needs to be enabled explicitly by specifying the desired log.level config option, as the log level is OFF by default. Currently, the client logs the following events, depending on the selected log.level value:

  • TRACE - low-level information about the Keep-Alive sockets lifecycle.
  • DEBUG - response information (without authorization headers and host info).
  • INFO - still mostly unused, will print the current log level when the client is initialized.
  • WARN - non-fatal errors; failed ping request is logged as a warning, as the underlying error is included in the returned result.
  • ERROR - fatal errors from query/insert/exec/command methods, such as a failed request.

Breaking changes

• keep_alive.retry_on_expired_socket and keep_alive.socket_ttl configuration parameters are removed.
• The max_open_connections configuration parameter is now 10 by default, as we should not rely on the KeepAlive agent's defaults.
• Fixed the default request_timeout configuration value (now it is correctly set to 30_000, previously 300_000 (milliseconds)).

Bug fixes

• Fixed a bug with Ping that could lead to an unhandled "Socket hang-up" propagation.
• Ensure proper Connection header value considering Keep-Alive settings. If Keep-Alive is disabled, its value is now forced to "close".

0.3.0-beta.1 (Node.js only)

See 0.3.0.

0.2.10 (Common, Node.js, Web)

New features

• If InsertParams.values is an empty array, no request is sent to the server and ClickHouseClient.insert short-circuits itself. In this scenario, the newly added InsertResult.executed flag will be false, and InsertResult.query_id will be an empty string.

Bug fixes

• Client no longer produces Code: 354. inflate failed: buffer error exception if request compression is enabled and InsertParams.values is an empty array (see above).