0.2.2 (Common, Node.js & Web)

New features

• Added missing default_format setting, which allows to perform exec calls without the FORMAT clause. See the example.

0.2.1 (Common, Node.js & Web)

Breaking changes

Date objects in query parameters are now serialized as time-zone-agnostic Unix timestamps (NNNNNNNNNN[.NNN], optionally with millisecond-precision) instead of datetime strings without time zones (YYYY-MM-DD HH:MM:SS[.MMM]). This means the server will receive the same absolute timestamp the client sent even if the client's time zone and the database server's time zone differ. Previously, if the server used one time zone and the client used another, Date objects would be encoded in the client's time zone and decoded in the server's time zone and create a mismatch.

For instance, if the server used UTC (GMT) and the client used PST (GMT-8), a Date object for "2023-01-01 13:00:00 PST" would be encoded as "2023-01-01 13:00:00.000" and decoded as "2023-01-01 13:00:00 UTC" (which is 2023-01-01 05:00:00 PST). Now, "2023-01-01 13:00:00 PST" is encoded as "1672606800000" and decoded as "2023-01-01 21:00:00 UTC", the same time the client sent.

Props to @ide for implementing it.

0.2.0 - Web platform support

Introduces web client (using native fetch and WebStream APIs) without Node.js modules in the common interfaces.
No polyfills are required.

The web client is confirmed to work with Chrome/Firefox/CloudFlare workers.

It is now possible to implement new custom connections on top of @clickhouse/client-common.

The repository was refactored into three packages:

• @clickhouse/client-common: all possible platform-independent code, types and interfaces
• @clickhouse/client-web: new web (or non-Node.js env) connection, uses native fetch.
• @clickhouse/client: Node.js connection as it was before.

Node.js client breaking changes

• Changed ping method behavior: it will not throw now.
  Instead, either { success: true } or { success: false, error: Error } is returned.
• Log level configuration parameter is now explicit instead of CLICKHOUSE_LOG_LEVEL environment variable.
  Default is OFF.
• query return type signature changed to is BaseResultSet<Stream.Readable> (no functional changes)
• exec return type signature changed to ExecResult<Stream.Readable> (no functional changes)
• insert<T> params argument type changed to InsertParams<Stream, T> (no functional changes)
• Experimental schema module is removed

Web client known limitations

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

0.2.0-beta1 (browser support)

Introduces browser client (using native fetch and WebStream APIs) with no Node.js modules in the common interfaces.
No polyfills are required.

It is now possible to implement new custom connections on top of @clickhouse/client-common.

The client was refactored into three packages:

• @clickhouse/client-common: all possible platform-independent code, types and interfaces
• @clickhouse/client-browser: new "browser" (or non-Node.js env) connection, uses native fetch.
• @clickhouse/client: Node.js connection as it was before.

Node.js client breaking changes

• Log level configuration parameter is now explicit instead of CLICKHOUSE_LOG_LEVEL environment variable.
  Default is OFF.
• query return type signature changed to is BaseResultSet<Stream.Readable> (no functional changes)
• exec return type signature changed to ExecResult<Stream.Readable> (no functional changes)
• insert<T> params argument type changed to InsertParams<Stream, T> (no functional changes)
• Experimental schema module is removed

Browser client known limitations

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

0.1.1

New features

• Expired socket detection on the client side when using Keep-Alive. If a potentially expired socket is detected,
  and retry is enabled in the configuration, both socket and request will be immediately destroyed (before sending the data),
  and the client will recreate the request. See ClickHouseClientConfigOptions.keep_alive for more details. Disabled by default.
• Allow disabling Keep-Alive feature entirely.
• TRACE log level.

Examples

Disable Keep-Alive feature

const client = createClient({
  keep_alive: {
    enabled: false,
  },
})

Retry on expired socket

const client = createClient({
  keep_alive: {
    enabled: true,
    // should be slightly less than the `keep_alive_timeout` setting in server's `config.xml`
    // default is 3s there, so 2500 milliseconds seems to be a safe client value in this scenario
    // another example: if your configuration has `keep_alive_timeout` set to 60s, you could put 59_000 here
    socket_ttl: 2500,
    retry_on_expired_socket: true,
  },
})

0.1.0

Breaking changes

• connect_timeout client setting is removed, as it was unused in the code.

New features

• command method is introduced as an alternative to exec.
  command does not expect user to consume the response stream, and it is destroyed immediately.
  Essentially, this is a shortcut to exec that destroys the stream under the hood.
  Consider using command instead of exec for DDLs and other custom commands which do not provide any valuable output.

Example:

// incorrect: stream is not consumed and not destroyed, request will be timed out eventually
await client.exec('CREATE TABLE foo (id String) ENGINE Memory')

// correct: stream does not contain any information and just destroyed
const { stream } = await client.exec('CREATE TABLE foo (id String) ENGINE Memory')
stream.destroy()

// correct: same as exec + stream.destroy()
await client.command('CREATE TABLE foo (id String) ENGINE Memory')

Bug fixes

• Fixed delays on subsequent requests after calling insert that happened due to unclosed stream instance when using low number of max_open_connections. See #161 for more details.
• Request timeouts internal logic rework (see #168)

0.0.16

Breaking changes

• Node.js 14 EOL as its maintenance phase has ended in April 2023. Node.js 16+ is now required to use the client.

Bug fixes

• Fix NULL parameter binding. As the HTTP interface expects \N instead of a 'NULL' string, it is now correctly handled for both null and explicitly undefined parameters. See the test scenarios for more details.

0.0.15

Bug fixes

• Fix Node.JS 19.x/20.x timeout error (@olexiyb)

0.0.14

New features

• Added support for JSONStrings, JSONCompact, JSONCompactStrings, JSONColumnsWithMetadata formats (@andrewzolotukhin).

0.0.13

New features

• query_id can now be overridden for all main client's methods: query, exec, insert.