Improvements

• Added a helping WARN level log message with a suggestion to check the keep_alive configuration if the client receives an ECONNRESET error from the server, which can happen when the server closes idle connections after a certain timeout, and the client tries to reuse such a connection from the pool. This can be especially helpful for new users who might not be aware of this aspect of HTTP connection management. The log message is only emitted if the keep_alive option is enabled in the client configuration, and it includes the server's keep-alive timeout value (if available) to assist with troubleshooting. (#597)

How to reproduce the issue that triggers the log message:

const client = createClient({
  // ...
  keep_alive: {
    enabled: true,
    // ❌ DON'T SET THIS VALUE SO HIGH IN PRODUCTION
    idle_socket_ttl: 1_000_000,
  },
  log: {
    level: ClickHouseLogLevel.WARN, // to see the warning logs
  },
})

for (let i = 0; i < 1000; i++) {
  await client.ping({
    // To use a regular query instead of the /ping endpoint
    // which might be configured differently on the server side
    // and have different timeout settings.
    select: true,
  })

  // Wait long enough to let the server close the idle connection,
  // but not too long to let the client remove it from the pool,
  // in other words try to hit the scenario when the race condition
  // happens between the server closing the connection and the client
  // trying to reuse it.
  await sleep(SERVER_KEEP_ALIVE_TIMEOUT_MS - 100)
}

Example log message:

{
  "message": "Ping: idle socket TTL is greater than server keep-alive timeout, try setting idle socket TTL to a value lower than the server keep-alive timeout to prevent unexpected connection resets, see https://c.house/js_keep_alive_econnreset for more details.",
  "args": {
    "operation": "Ping",
    "connection_id": "8dc1c9bd-7895-49b1-8a95-276470151c65",
    "query_id": "beee95af-2e83-4dcb-8e1e-045bd61f4985",
    "request_id": "8dc1c9bd-7895-49b1-8a95-276470151c65:2",
    "socket_id": "8dc1c9bd-7895-49b1-8a95-276470151c65:1",
    "server_keep_alive_timeout_ms": 10000,
    "idle_socket_ttl": 15000
  },
  "module": "HTTP Adapter"
}

Improvements

• Setting log.level default value to ClickHouseLogLevel.WARN instead of ClickHouseLogLevel.OFF to provide better visibility into potential issues without overwhelming users with too much information by default.

const client = createClient({
  // ...
  log: {
    level: ClickHouseLogLevel.WARN, // default is now ClickHouseLogLevel.WARN instead of ClickHouseLogLevel.OFF
  },
})

• Logging is now lazy, which means that the log messages will only be constructed if the log level is appropriate for the message. This can improve performance in cases where constructing the log message is expensive, and the log level is set to ignore such messages. See ClickHouseLogLevel enum for the complete list of log levels. (#520)

const client = createClient({
  // ...
  log: {
    level: ClickHouseLogLevel.TRACE, // to log everything available down to the network level events
  },
})

• Enhanced the logging of the HTTP request / socket lifecycle with additional trace messages and context such as Connection ID (UUID) and Request ID and Socket ID that embed the connection ID for ease of tracing the logs of a particular request across the connection lifecycle. To enable such logs, set the log.level config option to ClickHouseLogLevel.TRACE. (#567)

[2026-02-25T09:19:13.511Z][TRACE][@clickhouse/client][Connection] Insert: received 'close' event, 'free' listener removed
Arguments: {
  operation: 'Insert',
  connection_id: 'da3c9796-5dc5-46ef-83b0-ed1f4422094c',
  query_id: '9dfda627-39a2-41a6-9fc9-8f8716574826',
  request_id: 'da3c9796-5dc5-46ef-83b0-ed1f4422094c:3',
  socket_id: 'da3c9796-5dc5-46ef-83b0-ed1f4422094c:2',
  event: 'close'
}
[2026-02-25T09:19:13.502Z][TRACE][@clickhouse/client][Connection] Query: reusing socket
Arguments: {
  operation: 'Query',
  connection_id: 'da3c9796-5dc5-46ef-83b0-ed1f4422094c',
  query_id: 'ad0127e8-b1c7-4ed6-9681-c0162f7a0ea9',
  request_id: 'da3c9796-5dc5-46ef-83b0-ed1f4422094c:4',
  socket_id: 'da3c9796-5dc5-46ef-83b0-ed1f4422094c:2',
  usage_count: 1
}

• A step towards structured logging: the client now passes rich context to the logger args parameter (e.g. connection_id, query_id, request_id, socket_id). (#576)

Deprecated API

• The drainStream utility function is now deprecated, as the client will handle draining the stream internally when needed. Use client.command() instead, which will handle draining the stream internally when needed. (#578)

• The sleep utility function is now deprecated, as it is not intended to be used outside of the client implementation. Use setTimeout directly or a more full-featured utility library if you need additional features like cancellation or timers management. (#578)

New features

• Added http_status_code to query, insert, and exec commands (#525, [Kinzeng])
• Fixed ignore_error_response not getting passed when using command (#536, [Kinzeng])

New features

• Added support for the new Disposable API (a.k.a the using keyword) (#500)

async function main() {
  await using client = await client.query(…);

  // some code that can throw
  // but thanks to `using` the client will still get closed

  // client is also automatically closed here by calling [Symbol.disaposeAsync]
}

Without the new using keyword it is required to wrap the code that might leak expensive resources like sockets and big buffers in try / finally

async function main() {
  let client
  try {
    client = await createClient(…);
    // some code that can throw
  } finally {
    if (client) {
      await client.close()
    }
  }
}

New features

• Added support for BigInt values in query parameters. (#487, @dalechyn)

New features

• It is now possible to specify custom parse and stringify functions that will be used instead of the standard JSON.parse and JSON.stringify methods for JSON serialization/deserialization when working with JSON* family formats. See ClickHouseClientConfigOptions.json, and a new custom_json_handling example for more details. (#481, looskie)
• (Node.js only) Added an ignore_error_response param to ClickHouseClient.exec, which allows callers to manually handle request errors on the application side. (#483, Kinzeng)

New features

• Server-side exceptions that occur in the middle of the HTTP stream are now handled correctly. This requires ClickHouse 25.11+. Previous ClickHouse versions are unaffected by this change. (#478)

Improvements

• TupleParam constructor now accepts a readonly array to permit more usages. (#465, Malien)

Bug fixes

• Fixed boolean value formatting in query parameters. Boolean values within Array, Tuple, and Map types are now correctly formatted as TRUE/FALSE instead of 1/0 to ensure proper type compatibility with ClickHouse. (#475, baseballyama)

Improvements

• Improved performance of toSearchParams. (#449, twk)

Other

• Added Node.js 24.x to the CI matrix. Node.js 18.x was removed from the CI due to EOL.

Types

• Add missing allow_experimental_join_condition to ClickHouseSettings typing. (#430, looskie)
• Fixed JSONEachRowWithProgress TypeScript flow after the breaking changes in ClickHouse 25.1. RowOrProgress<T> now has an additional variant: SpecialEventRow<T>. The library now additionally exports the parseError method, and newly added isRow / isException type guards. See the updated JSONEachRowWithProgress example (#443)
• Added missing allow_experimental_variant_type (24.1+), allow_experimental_dynamic_type (24.5+), allow_experimental_json_type (24.8+), enable_json_type (25.3+), enable_time_time64_type (25.6+) to ClickHouseSettings typing. (#445)

Improvements

• Add a warning on a socket closed without fully consuming the stream (e.g., when using query or exec method). (#441)
• (Node.js only) An option to use a simple SELECT query for ping checks instead of /ping endpoint. See the new optional argument to the ClickHouseClient.ping method and PingParams typings. Note that the Web version always used a SELECT query by default, as the /ping endpoint does not support CORS, and that cannot be changed. (#442)

Other

• The project now uses Codecov instead of SonarCloud for code coverage reports. (#444)

A minor release to allow further investigation regarding uncaught error issues with #410.

Types

• Added missing lightweight_deletes_sync typing to ClickHouseSettings (#422, pratimapatel2008)

Improvements (Node.js)

• Added a new configuration option: capture_enhanced_stack_trace; see the JS doc in the Node.js client package. Note that it is disabled by default due to a possible performance impact. (#427)
• Added more try-catch blocks to the Node.js connection layer. (#427)