Update dependency @clickhouse/client to v1.23.1

[renovate]

This PR contains the following updates:

Package	Type	Update	Change	OpenSSF
@clickhouse/client (source)	dependencies	minor	1.18.2 → 1.23.1

---

Release Notes

ClickHouse/clickhouse-js (@​clickhouse/client)

v1.23.1

Compare Source

v1.23.0

Compare Source

Migration Notes

• Node.js 26.x was added to the CI matrix, and Node.js 18.x is no longer supported. The engines.node floor of @clickhouse/client (previously >=16) and @clickhouse/datatype-parser (previously >=18.0.0) was raised to >=20. Node.js 20.x, 22.x, 24.x, and 26.x are supported and exercised in CI.

• The @clickhouse/client-common package is deprecated. @clickhouse/client (Node.js) and @clickhouse/client-web (Web) no longer depend on it; the shared code is now bundled into each client package. Everything previously importable from @clickhouse/client-common should be imported from @clickhouse/client or @clickhouse/client-web instead. The @clickhouse/client-common package itself will no longer receive updates. ([#​845])

• The parseColumnType function and its SimpleColumnTypes companion (exported from @clickhouse/client, @clickhouse/client-web, and @clickhouse/client-common) are deprecated and slated for removal in a future major version. They are superseded by the new standalone @clickhouse/datatype-parser package (parseDataType plus its Node AST), which parses the full ClickHouse data-type grammar and emits an AST that mirrors the server's. ([#​893])

New features

• (Node.js) Added a RowBinary reader library and agent skill under skills/clickhouse-js-node-rowbinary-parser. It ships type-specific, monomorphizable building blocks for decoding RowBinary / RowBinaryWithNames / RowBinaryWithNamesAndTypes streams (full-buffer and chunked), plus a skill that guides an agent to generate bespoke high-performance parsers from a query's column types. The skill is bundled into @clickhouse/client (registered in agents.skills) and is also published independently as the @clickhouse/rowbinary package. A matching RowBinary writer is planned. ([#​864])

• Published the @clickhouse/datatype-parser package: a small, dependency-free standalone parser for ClickHouse data-type strings (the kind sent in the types row of RowBinaryWithNamesAndTypes, e.g. Array(Nullable(UInt64)), Tuple(a UInt8, b String), Enum8('a' = 1)). It is a faithful port of the server's ParserDataType and emits a JSON AST that is byte-identical to the server's EXPLAIN AST json = 1 data-type subtree. It supersedes the deprecated parseColumnType (see Migration Notes). ([#​893])

• (Node.js, @experimental) Added an additive connection?: Connection<Stream.Readable> option to createClient that lets a caller plug an externally-built backend Connection-like object in place of the default HTTP(S) factory. Only supposed to be used for testing the chDB integration. ([#​879])

• Added ClickHouseSettingsInterface, a package-neutral structural counterpart to ClickHouseSettings, exported from @clickhouse/client, @clickhouse/client-web, and @clickhouse/client-common. It is identical to ClickHouseSettings except that its index signature omits SettingsMap (a class with a private member, which TypeScript compares nominally). Because each client package now bundles its own copy of the common module, their ClickHouseSettings types are mutually unassignable; ClickHouseSettingsInterface is structurally identical across all three packages and assignable into each package's ClickHouseSettings, so a consumer that shares a single settings-producing helper across both the Node.js and Web clients can type it against this one type without casts. Values typed as SettingsMap cannot be carried through it — use ClickHouseSettings if you need them. ([#​889])

v1.22.0

Compare Source

New features

• (Node.js) The compression.request / compression.response client options now accept an explicit codec via an object, in addition to the existing boolean: true keeps gzip (backwards compatible), and { codec: "zstd" } selects zstd. The object form is intentionally extensible for future codecs and codec-specific options. zstd typically yields a similar-or-better ratio than gzip at noticeably lower CPU cost (gzip/DEFLATE is comparatively CPU-heavy and decompressed single-threaded by the ClickHouse server), and it uses the built-in zlib zstd support, so it requires Node.js >= 22.15.0 (@clickhouse/client throws a clear error at client creation otherwise). Response decompression is driven by the server's actual Content-Encoding, so it degrades gracefully. The request object form also accepts an optional level ({ codec, level }) to set the codec-specific compression level (zlib level for gzip, zstd compression level for zstd); the response compression level is controlled by the server. Supported only by @clickhouse/client (Node.js); @clickhouse/client-web rejects the zstd codec at client creation.

• (Node.js) Brotli ({ codec: "br" }) is now supported for compression.request / compression.response, alongside gzip and zstd. Unlike zstd, Brotli is available on every supported Node.js version (no minimum-version requirement). The compression.request option is a per-codec discriminated union, so each codec exposes its own tuning option: a level for gzip/zstd, a quality for Brotli ({ codec: "br", quality }). When omitted, Brotli defaults to quality 4 for request bodies, since zlib's brotli default of 11 (max) is far too slow for a streaming insert path. Response decompression follows the server's Content-Encoding. Supported only by @clickhouse/client (Node.js).

Internal changes (@clickhouse/client-common)

These only affect code that imports the low-level connection primitives from the deprecated @clickhouse/client-common package directly (e.g. a custom Connection implementation). The createClient compression option is unchanged and fully backwards compatible — if you only use @clickhouse/client or @clickhouse/client-web, you are not affected.

To carry the codec (and its optional compression level) instead of a bare on/off flag, the internal compression representation changed shape:

• CompressionSettings.compress_request / decompress_response are no longer boolean. They are now a normalized codec object or undefined (disabled): { codec: "gzip" | "zstd"; level?: number } | { codec: "br"; quality?: number } for the request, { codec: "gzip" | "zstd" | "br" } for the response (response compression options are chosen by the server). getConnectionParams normalizes the public request option into this form (true → { codec: "gzip" }).
• withCompressionHeaders now takes request_compression_codec / response_compression_codec (a CompressionMethod | undefined) instead of the boolean enable_request_compression / enable_response_compression; the codec value is also the Content-Encoding / Accept-Encoding it emits.
• withHttpSettings now takes the response codec object ({ codec } | undefined) instead of a boolean.
• New exported types: CompressionMethod, RequestCompression, ResponseCompression.

Why: a single boolean could not express which codec to use or its level, and a separate level field on CompressionSettings would have mixed a codec-specific option into the shared type. Discriminating by codec keeps each codec's options on the codec it belongs to.

Documentation

• Added two tracer adapter recipes to docs/howto/tracing.md and examples/node/coding/otel_tracing.ts, demonstrating how common OpenTelemetry auto-instrumentation options compose as thin userland wrappers around the tracer API instead of being baked into the client: requireParentSpan (skip ClickHouse spans when there is no active parent span — e.g. background health checks) and suppressing the duplicate nested HTTP spans emitted by @opentelemetry/instrumentation-http (via suppressTracing from @opentelemetry/core).

v1.21.0

Compare Source

New features

• The tracer API (unreleased, introduced in #​776) now follows the OpenTelemetry database semantic conventions and matches the attribute vocabulary of the Rust client (clickhouse-rs); see docs/howto/tracing.md for the documentation. In particular (#​828):

  • Spans now carry db.system.name (instead of db.system), server.address + server.port (instead of a combined host:port), clickhouse.request.query_id / clickhouse.request.session_id (instead of clickhouse.query_id / clickhouse.session_id), clickhouse.response.format on query and clickhouse.request.format on insert (instead of clickhouse.format), and db.operation.name + db.collection.name on insert (instead of clickhouse.table).
  • The span status is left unset on success (per the OTEL spec recommendation for client spans, previously set to OK); on failure, the span gets the error.type attribute (the error class name) and, for server-side errors, clickhouse.error.code (the numeric ClickHouse error code).
  • Spans record response-side attributes: db.response.status_code (HTTP status) and, when the X-ClickHouse-Summary header is available, clickhouse.summary.* counters (read_rows, written_rows, etc.).
  • query() now emits two spans: clickhouse.query covers the HTTP request lifetime and ends as soon as the response headers are received; a child clickhouse.query.stream span is handed to the ResultSet and tracks the stream consumption, ending when the response is fully read, closed, or fails - with the final clickhouse.response.decoded_bytes and (for row-streaming) db.response.returned_rows metrics. This separation makes it easy to distinguish the original request duration from a stream that may never end (e.g. tailing a live table).
  • Fixed a span leak in the Web ResultSet.stream() path: if the underlying fetch response stream was aborted (e.g. due to a network error), the clickhouse.query.stream span was never ended. The TransformStream now handles both source-stream aborts and consumer-side cancellations via a cancel callback.
  • The insert span records clickhouse.request.sent_rows for array-based inserts.

• Added a use_multipart_params_auto client option (default: false). When enabled, query() automatically sends query_params as multipart/form-data body parts (the same mechanism as use_multipart_params) once their URL-encoded length exceeds 4096 characters, avoiding HTTP 414/400 errors from HTTP intermediaries (nginx, AWS ALB, CloudFront) caused by over-long URLs - for example, a large IN list or a high-dimensional vector embedding. Smaller parameter payloads remain in the URL query string, so existing behavior is unchanged unless the threshold is crossed. use_multipart_params: true still forces multipart for all queries regardless of size. This does not change the server's per-value size limit, which is governed by http_max_field_value_size. Supported on both @clickhouse/client and @clickhouse/client-web, and overridable per request via use_multipart_params_auto on query(). Ported from clickhouse-connect#789. (#​827)

const client = createClient({ use_multipart_params_auto: true });

await client.query({
  query: "SELECT * FROM events WHERE id IN {ids:Array(UInt64)}",
  // Sent in the URL when small, auto-promoted to the multipart body when large
  query_params: { ids: veryLargeArrayOfIds },
});

• Added a use_multipart_params client option (default: false). When enabled, query() sends query_params as multipart/form-data body parts (with the SQL moved into a query part) instead of URL query-string entries, avoiding HTTP 400 errors caused by over-long URLs when parameters contain large arrays (25K+ values). All other URL search params (database, query_id, settings, session_id, role) remain in the URL. Supported on both @clickhouse/client and @clickhouse/client-web, and overridable per request via use_multipart_params on query(). (#​825)

const client = createClient({ use_multipart_params: true });

await client.query({
  query: "SELECT * FROM events WHERE id IN {ids:Array(UInt64)}",
  query_params: { ids: veryLargeArrayOfIds },
  // Per-request override is also supported:
  // use_multipart_params: false,
});

Bug Fixes

• The client now checks the X-ClickHouse-Exception-Code response header to detect server errors even when the HTTP status code indicates success. In some scenarios (for example, when an exception occurs while streaming the response progress in headers, or with certain proxy setups), ClickHouse responds with HTTP 200 but sets the X-ClickHouse-Exception-Code header. Previously, such responses were treated as successful, and the exception text could surface as malformed response data; now the request is rejected with a parsed ClickHouseError (with the proper code and type), consistent with non-2xx error responses. This applies to both the Node.js and Web clients. (#​554, supersedes #​350, related issue: #​332)

v1.20.0

Compare Source

New Features

• Added an optional tracer API that the user can pass through the client config (tracer) and that gets called around key lifecycle operations (query, command, exec, insert, ping). The ClickHouseTracer interface is a structural subset of the OpenTelemetry Tracer/Span APIs, so a raw OTEL tracer (trace.getTracer(...)) can be passed to the client as-is - but the client itself ships no tracing dependency. Each operation runs inside tracer.startActiveSpan(...), so auto-instrumented child spans nest under the ClickHouse operation spans; for OpenTelemetry, this requires the AsyncLocalStorageContextManager to be registered (the default in the OpenTelemetry Node.js SDK). Tracer exceptions are NOT caught, so a broken tracer will break client operations. See docs/howto/tracing.md for the full surface description, and examples/node/coding/otel_tracing.ts for a runnable Node.js example. ([#​776])

import { createClient } from "@clickhouse/client";
import { trace } from "@opentelemetry/api";

// a raw OpenTelemetry tracer is structurally compatible - no adapter needed
const client = createClient({
  url: "http://localhost:8123",
  tracer: trace.getTracer("@clickhouse/client"),
});

Migration Notes

• TypeScript: ClickHouseLogLevel is now exported as a literal numeric union type (0 | 1 | 2 | 3 | 4 | 127) instead of a TypeScript enum type. If you were assigning arbitrary number values to ClickHouseLogLevel, you may need to narrow/cast those values during migration.

Improvements

• Added TypeScript typings for the remaining HTTP-specific ClickHouse settings, so they are now suggested by autocomplete when used in clickhouse_settings: buffer_size, compress, decompress, quota_key, and stacktrace (in addition to the existing wait_end_of_query, default_format, session_timeout, and session_check).

await client.query({
  query: "SELECT 1",
  clickhouse_settings: {
    // Buffer the entire response on the server before sending it to the client
    wait_end_of_query: 1,
    buffer_size: "1048576",
  },
});

Bug Fixes

• (Node.js only) Fixed a race condition in ResultSet.json() and ResultSet.stream() on JSONEachRow (and other streamable) result sets where calling json() on a fast/small response could throw Stream has been already consumed if the underlying stream ended between internal readableEnded checks. The consumption guard has been hardened: the stream is now shielded through a single consume() path that marks the result set as consumed in the appropriate branches, after format validation, so a successful json() call no longer races against the stream finishing. (#​603)

v1.19.0

Compare Source

Improvements

• Re-exported the ResponseHeaders type from @clickhouse/client and @clickhouse/client-web. Previously this type was only available from @clickhouse/client-common; it is now part of the public re-export surface of both flavored packages, alongside the other commonly used types. This is part of an ongoing effort to make @clickhouse/client-common an internal-only package so downstream consumers can depend solely on @clickhouse/client or @clickhouse/client-web. (#​758)

Bug Fixes

• Enum type parsing now correctly unescapes backslash escape sequences in enum names. Previously, parseEnumType returned enum names with raw escape sequences (e.g., f\' instead of f'). Now it properly decodes escape sequences including \' (single quote), \\ (backslash), \n (newline), \t (tab), and \r (carriage return). This matches the behavior of ClickHouse string literals and ensures consistency with how the client encodes strings when sending data to the server. If you were relying on the previous incorrect behavior where backslash escape sequences were preserved in enum names, you will need to update your code to handle properly unescaped values.

Example:

// Before (incorrect):
parseEnumType({
  columnType: "Enum8('f\\'' = 1)",
  sourceType: "Enum8('f\\'' = 1)",
});
// returned: { values: { 1: "f\\'" } }  // with backslash

// After (correct):
parseEnumType({
  columnType: "Enum8('f\\'' = 1)",
  sourceType: "Enum8('f\\'' = 1)",
});
// returns: { values: { 1: "f'" } }     // unescaped

v1.18.5

Compare Source

Improvements

• (Node.js only) Added max_response_headers_size client option that forwards the maxHeaderSize option to the underlying http(s).request call. This raises the per-request limit on the total size of HTTP response headers received from the server (Node.js default is ~16 KB). It is most useful when running long-running queries with send_progress_in_http_headers enabled — the X-ClickHouse-Progress headers accumulate over the lifetime of the request and can exceed the default limit, causing the request to fail with HPE_HEADER_OVERFLOW. Setting this option avoids the need to use the global --max-http-header-size Node.js CLI flag or the NODE_OPTIONS environment variable. Has no effect for the Web client (which uses fetch) and no effect when a custom http_agent is configured with a request implementation that does not honor the option.

const client = createClient({
  request_timeout: 400_000,
  max_response_headers_size: 1024 * 1024, // accept up to 1 MiB of response headers
  clickhouse_settings: {
    send_progress_in_http_headers: 1,
    http_headers_progress_interval_ms: "110000",
  },
});

• The @clickhouse/client npm package now ships embedded AI-agent skills, clickhouse-js-node-coding and clickhouse-js-node-troubleshooting, under node_modules/@clickhouse/client/skills/. These skills are also declared in the agents.skills field of the package manifest for discovery tools that scan node_modules. This allows agentic coding tools to load focused, Node-client-specific coding and troubleshooting guidance without any additional setup. (#​682)

v1.18.4

Compare Source

A release-infrastructure-only version bump (no user-facing changes). See 1.18.5 for the next release with user-facing improvements.

v1.18.3

Compare Source

Improvements

• Added keep_alive.eagerly_destroy_stale_sockets option (Node.js only, default: false). When enabled, sockets that have been idle for longer than idle_socket_ttl are destroyed immediately before each request, rather than waiting for the idle timeout to fire. This helps reclaim stale sockets during event loop delays, where the timeout callback may not run on time.

const client = createClient({
  keep_alive: {
    enabled: true,
    idle_socket_ttl: 2500,
    eagerly_destroy_stale_sockets: true,
  },
});

• Added auto-detection and warning when request_timeout is high (> 60 seconds) but progress headers are not configured. Long-running queries may fail with socket hang-up errors if they exceed the load balancer idle timeout. The client now warns users to enable send_progress_in_http_headers and http_headers_progress_interval_ms settings to prevent such issues.

// This will now trigger a warning
const client = createClient({
  request_timeout: 120_000, // 120 seconds
  // send_progress_in_http_headers is not configured
});

// ✓ Properly configured to avoid load balancer timeouts
const client = createClient({
  request_timeout: 400_000,
  clickhouse_settings: {
    send_progress_in_http_headers: 1,
    http_headers_progress_interval_ms: "110000", // ~10s below LB timeout
  },
});

---

Configuration

📅 Schedule: (UTC)

• Branch creation
  • Between 12:00 AM and 03:59 AM (* 0-3 * * *)
• Automerge
  • At any time (no schedule defined)

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-ui	Ready	Preview, Comment	Jul 7, 2026 4:49pm
react-ui-tooling	Ready	Preview, Comment	Jul 7, 2026 4:49pm

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Awaiting the start of a new Argos build…