1.20 Alpha 2 by peter-leonov-ch · Pull Request #806 · ClickHouse/clickhouse-js

peter-leonov-ch · 2026-06-03T19:34:12Z

Summary

A short description of the changes with a link to an open issue.

Checklist

Delete items not relevant to your PR:

Unit and integration tests covering the common scenarios were added
A human-readable description of the changes was provided to include in CHANGELOG
For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

## Summary Adds `ALTERNATIVE_CLIENTS.md` to encourage and streamline third-party clients for other runtimes (Bun, Cloudflare Workers, …) and protocols (native TCP, gRPC-over-proxy, …) now that `@clickhouse/client-common` is being deprecated and there is no replacement shared package. - **New `ALTERNATIVE_CLIENTS.md` (root)** covering: - Why `@clickhouse/client-common` is going away (versioning + bundling pain) and that shared code is being inlined into each runtime package rather than relocated to a new shared folder/package — new clients should copy what they need, not depend on a shared package. - Recommended workflow: fork `packages/client-node` or `packages/client-web` in place (whichever is closest to the target runtime), iterate until it works, then rename the directory to e.g. `packages/my-native-client`, update `package.json#name`, and open a PR. - Request to **preserve commit history** (no squash/rewrite) so the diff against the upstream package stays analyzable for reviewers and future syncs. - Strong nudge to **open an issue and discuss the design first** before significant work. - Pre-PR checklist (issue exists, no `client-common` dep, history preserved, tests, build/lint pass). - **`README.md`**: link the new doc from the Contributing section. ## Checklist - [x] A human-readable description of the changes was provided to include in CHANGELOG --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Peter Leonov <peter.leonov@clickhouse.com>

## Summary The code review agent had no explicit guidance on breaking changes. Undocumented breaks in the public API degrade LLM-generated code for newer client versions, since models lean on older-version training data. Added a "Breaking changes" section to `.github/instructions/review.instructions.md` instructing the agent to flag major public-API breaks (removed/renamed exports, changed signatures, changed defaults, removed config) that lack a clear justification in the PR description, commit, or comments, and to request either a rationale/migration note or a backwards-compatible path (e.g., deprecation). ## Checklist - [x] A human-readable description of the changes was provided to include in CHANGELOG --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Peter Leonov <peter.leonov@clickhouse.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

## Summary A short description of the changes with a link to an open issue. ## Checklist Delete items not relevant to your PR: - [ ] Unit and integration tests covering the common scenarios were added - [ ] A human-readable description of the changes was provided to include in CHANGELOG - [ ] For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

Adds the AI usage policy from the main ClickHouse repository: https://github.com/ClickHouse/ClickHouse/blob/master/AI_POLICY.md This makes the policy consistent across ClickHouse client/driver repositories.

## Summary A short description of the changes with a link to an open issue. ## Checklist Delete items not relevant to your PR: - [ ] Unit and integration tests covering the common scenarios were added - [ ] A human-readable description of the changes was provided to include in CHANGELOG - [ ] For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

…stic, and add Bun CI workflow (#795) ## Summary Adds scripts to run the existing Vitest unit suites under Bun (`bun --bun vitest`), fixes the `getAsText` "response too large" handling which was V8-only, and introduces a dedicated GitHub Actions workflow to run the Bun unit tests in CI. Running the Node unit suite under Bun surfaced two failures in `node_getAsText`: JavaScriptCore throws `RangeError: Out of memory` (not V8's `Invalid string length`) past the string limit, and its `MAX_STRING_LENGTH` differs (2147483647 vs V8's 536870888). - **Bun test scripts**: `test:node:unit:bun` and `test:common:unit:bun` in root `package.json` run the existing suites via `bun --bun vitest`. - **`getAsText` (`packages/client-node/src/utils/stream.ts`)**: also catches the JSC `Out of memory` RangeError; error message is now engine-neutral (`maximum allowed size of a string`) instead of `V8 String`. - **`node_getAsText` test**: length assertions derive from `constants.MAX_STRING_LENGTH` rather than a hard-coded V8 value, so they hold under both engines. - **Bun CI workflow** (`.github/workflows/tests-bun.yml`): separate workflow with `common-unit-tests-bun` and `node-unit-tests-bun` jobs, triggered on push/PR/`workflow_dispatch`, using `oven-sh/setup-bun` (pinned by SHA). The full Node unit suite (131 tests) passes under both Node and Bun. ## Checklist - [x] Unit and integration tests covering the common scenarios were added - [x] A human-readable description of the changes was provided to include in CHANGELOG --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Inserting a UUID string into a `UInt128` column via `JSONEachRow` fails with `CANNOT_PARSE_INPUT_ASSERTION_FAILED` because ClickHouse only converts UUID → UInt128 implicitly for the `VALUES` clause. The client correctly forwards the JSON unchanged; users need guidance on the supported patterns. ## Summary Adds a new example (Node + Web) demonstrating two working approaches, with a round-trip assertion proving the server stores the value byte-for-byte. - **`examples/{node,web}/coding/insert_uuid_into_uint128.ts`** — two patterns: - *Client-side conversion* (recommended): `BigInt('0x' + uuid.replace(/-/g, '')).toString()` passed as the UInt128 column value. - *EPHEMERAL UUID column*: `UInt128 DEFAULT id_uuid` + `UUID EPHEMERAL` paired with `insert({ columns: ['id_uuid', ...] })`. - **Round-trip assertion** after each `SELECT` (`node:assert/strict` in Node; tiny inline `assertEqual` in Web, since `node:assert` isn't browser-compatible). Both patterns produce the same UInt128 decimal `2126302229887840375125392584261985180`. - **`examples/README.md`** — new row in the `coding/` table. ```ts function uuidToUInt128(uuid: string): string { return BigInt('0x' + uuid.replace(/-/g, '')).toString() } await client.insert({ table, values: [{ id: uuidToUInt128(uuid), description: '...' }], format: 'JSONEachRow', }) ``` ## Checklist - [x] A human-readable description of the changes was provided to include in CHANGELOG ### Release note Added `examples/{node,web}/coding/insert_uuid_into_uint128.ts` showing how to insert a UUID into a `UInt128` column with `JSONEachRow`, either via client-side BigInt conversion or via an `EPHEMERAL` UUID column with a `UInt128 DEFAULT` expression, with a round-trip assertion verifying the stored value. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

## Summary Swaps vitest `expect()` for Node's built-in `node:assert` in the Node QBit example, per reviewer preference for native assertions. - **Node example** (`examples/node/coding/qbit.ts`): `import { expect } from 'vitest'` → `import assert from 'node:assert'`; `toEqual` → `assert.deepStrictEqual`, `toBe` → `assert.strictEqual`, `toMatch` → `assert.match`. - **Web example** (`examples/web/coding/qbit.ts`): left on vitest `expect()`. It runs in a real browser (Playwright), where `node:assert` is externalized (`Module "node:assert" has been externalized for browser compatibility`) and unusable; no native throwing assert exists in browsers. ```ts import assert from 'node:assert' assert.deepStrictEqual(rows, values) assert.strictEqual(nearest[0].dist, 0) assert.match(row.bit_plane_1_hex, /^[0-9A-F]*$/) ``` ## Checklist - [ ] A human-readable description of the changes was provided to include in CHANGELOG --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

## Summary A short description of the changes with a link to an open issue. ## Checklist Delete items not relevant to your PR: - [ ] Unit and integration tests covering the common scenarios were added - [ ] A human-readable description of the changes was provided to include in CHANGELOG - [ ] For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

CLAassistant · 2026-06-03T19:34:20Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 3 committers have signed the CLA.

✅ peter-leonov-ch
✅ mshustov
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

Copilot

Pull request overview

This PR expands the repo’s documentation/examples (notably around QBit and UUID↔UInt128 pitfalls), adds Bun CI coverage for unit tests, and tweaks Node stream-to-text handling to better match Bun’s RangeError behavior.

Changes:

Added Bun unit test scripts and a dedicated GitHub Actions workflow for running common + node unit tests under Bun.
Added new docs/examples for QBit vector type and for inserting UUIDs into UInt128 in JSON row formats; added troubleshooting guidance for query()/FORMAT-clause pitfalls and a new “alternative clients” guide.
Updated Node getAsText() error handling/message and adjusted its unit tests accordingly; bumped a couple dev dependency versions.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
skills/clickhouse-js-node-troubleshooting/SKILL.md	Adds/extends troubleshooting index entries (incl. FORMAT/SHOW POLICIES).
skills/clickhouse-js-node-troubleshooting/reference/socket-hangup.md	Clarifies header-size limit workaround and mentions client option mapping.
skills/clickhouse-js-node-troubleshooting/reference/query-format-clause.md	New troubleshooting doc explaining duplicate `FORMAT` and `SHOW POLICIES` syntax issues with `query()`.
skills/clickhouse-js-node-troubleshooting/reference/data-types.md	Adds UUID→UInt128 JSON insertion caveat and mitigation patterns.
skills/clickhouse-js-node-coding/SKILL.md	Updates coding skill index; mentions QBit and UUID→UInt128 insert nuance.
skills/clickhouse-js-node-coding/reference/insert-values.md	Adds a dedicated UUID→UInt128 section + pitfall entry.
skills/clickhouse-js-node-coding/reference/insert-formats.md	Minor formatting/wording consolidation.
skills/clickhouse-js-node-coding/reference/data-types.md	Adds QBit coverage + example and related pitfalls.
README.md	Links to the new alternative clients guide.
packages/client-node/src/utils/stream.ts	Treats Bun/JSC “Out of memory” RangeError similarly to V8 “Invalid string length”.
packages/client-node/tests/unit/node_getAsText.test.ts	Updates assertions and makes size expectations parameterized.
package.json	Adds Bun test scripts; bumps a couple dev dependencies.
examples/web/coding/qbit.ts	New web QBit example (round-trip + approximate search + bit-plane notes).
examples/web/coding/insert_uuid_into_uint128.ts	New web example for UUID→UInt128 insertion patterns.
examples/README.md	Adds rows linking to the new examples (UUID→UInt128, QBit).
examples/node/coding/qbit.ts	New node QBit example.
examples/node/coding/insert_uuid_into_uint128.ts	New node example for UUID→UInt128 insertion patterns.
CHANGELOG.md	Re-categorizes the enum-unescape entry under “Bug Fixes”.
ALTERNATIVE_CLIENTS.md	New contributor doc for building alternative-runtime/protocol clients.
AI_POLICY.md	Adds a repository AI usage policy document.
.github/workflows/tests-bun.yml	New CI workflow to run unit tests under Bun.
.github/instructions/review.instructions.md	Adds explicit guidance to flag undocumented breaking API changes during review.

codecov · 2026-06-03T19:45:50Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

## Summary A short description of the changes with a link to an open issue. ## Checklist Delete items not relevant to your PR: - [ ] Unit and integration tests covering the common scenarios were added - [ ] A human-readable description of the changes was provided to include in CHANGELOG - [ ] For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

github-advanced-security · 2026-06-03T19:57:25Z

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

) ## Summary The `tests` workflow ran node and web jobs together under a single workflow and `success` gate, making runs harder to read and status checks coarse-grained. This splits it into two independent workflows. - **`tests-node.yml`** (`node`): `code-quality`, `common-unit-tests`, `unit-tests`, integration jobs (single-node, cluster, cloud), `codecov-upload`, plus a node-only `success` gate. - **`tests-web.yml`** (`web`): `common-unit-tests`, `all-tests-local-single-node`, integration jobs (cluster, cloud), `codecov-upload`, plus a web-only `success` gate. - Removed the combined `tests.yml`. - README now shows two CI badges (node, web) instead of one. - Both `codecov-upload` jobs use a `clickhouse: [head, latest]` matrix, consistent with the other integration test jobs in each workflow, and pass `CLICKHOUSE_VERSION` to docker-compose accordingly. - Job IDs within each workflow omit the redundant `node-`/`web-` prefix (e.g. `unit-tests` instead of `node-unit-tests`) since the workflow name already provides that context. Triggers, `permissions`, `concurrency`, and `env` are preserved in both. `code-quality` (repo-wide build/typecheck/lint) lives in the node workflow; concurrency groups key on `github.workflow`, so the two run independently. ## Checklist - [ ] A human-readable description of the changes was provided to include in CHANGELOG --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Peter Leonov <peter.leonov@clickhouse.com>

Copilot AI and others added 9 commits June 1, 2026 12:29

Add AI_POLICY.md (#786)

4ad8457

Adds the AI usage policy from the main ClickHouse repository: https://github.com/ClickHouse/ClickHouse/blob/master/AI_POLICY.md This makes the policy consistent across ClickHouse client/driver repositories.

Copilot AI review requested due to automatic review settings June 3, 2026 19:34

peter-leonov-ch requested a review from mshustov as a code owner June 3, 2026 19:34

Copilot started reviewing on behalf of peter-leonov-ch June 3, 2026 19:34 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

Comment thread skills/clickhouse-js-node-coding/reference/insert-values.md

Comment thread skills/clickhouse-js-node-troubleshooting/reference/data-types.md

peter-leonov-ch merged commit 97f135e into release Jun 3, 2026
137 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

1.20 Alpha 2#806

1.20 Alpha 2#806
peter-leonov-ch merged 11 commits into
releasefrom
main

peter-leonov-ch commented Jun 3, 2026

Uh oh!

CLAassistant commented Jun 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jun 3, 2026

Uh oh!

github-advanced-security AI commented Jun 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

peter-leonov-ch commented Jun 3, 2026

Summary

Checklist

Uh oh!

CLAassistant commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jun 3, 2026

Codecov Report

Uh oh!

github-advanced-security AI commented Jun 3, 2026

What Enabling Code Scanning Means:

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

CLAassistant commented Jun 3, 2026 •

edited

Loading