[ShawnChen-Sirius]

What

Ships the chdb/connection public surface — a ChdbConnection class that implements @clickhouse/client-common's Connection<Stream.Readable> interface and plugs into @clickhouse/client's createClient({ connection }) injection point (companion PR: ClickHouse/clickhouse-js#879, tracking issue ClickHouse/clickhouse-js#865).

import { createClient } from '@clickhouse/client';
import { createChdbConnection } from 'chdb/connection';

const client = createClient({
  connection: createChdbConnection({ path: ':memory:' }),
});

After that, all client.* methods work the same as against a remote ClickHouse server. Switching backends is one extra import + one line.

Stacked on #51

This PR's base is feat/layer1-multi-conn (#51 — Layer 1 multi-connection model). ChdbConnection's :memory: refcount semantics require N parallel connections to one bound path, which is what #51 introduces. Please merge #51 first. After merge, this PR's base will auto-update to main.

Shape (6 commits)

1. feat(connection): Connection interface + ChdbConnection implementation — re-exports Connection<Stream.Readable> verbatim from @clickhouse/client-common (we don't define our own lookalike), and the class implementing it on top of Layer 1 Session. Includes withClickHouseError reshape (chdb errors come out as ClickHouseError with .code/.type/.message); HTTP_ONLY_SETTINGS filter so HTTP-side settings like wait_end_of_query don't blow up against the embedded engine; default_format rerouted to chdb's queryAsync format opt; query_params routed through queryBindAsync; empty-body insert/exec short-circuit.
2. feat(connection): .chdb extension namespace — conn.chdb.queryAsync / queryStream / rawInsert / session.path for chdb-native escape hatches (zero-copy bytes, Arrow, raw passthrough insert) that don't fit the cross-backend contract.
3. feat(test-suite): clickhouse-js parity runner + skip_list — tests/clickhouse-js/runner.mjs clones @clickhouse/client at the ref configured in skip_list.json#syncedAgainst.ref, links this checkout in, injects ChdbConnection via globalThis.environmentSpecificCreateClient, and runs the full integration suite with the skip list applied. Result today: 202 passing / 30 skipped / 0 failing.
4. test(connection): contract suite + vitest CJS-externalize fix — test/v3/connection/contract.test.ts pins the cross-backend invariants (15 tests). vitest.config.ts gains server.deps.external: [/\/index\.js$/] so the CJS entrypoint isn't double-evaluated.
5. ci(connection): contract + cross-suite parity workflow — two-job CI: fast contract on every PR, slower parity that runs the upstream suite via runner.mjs.
6. docs: pluggable Connection design + clickhouse-js sync policy — docs/design/pluggable-connection.md covers the upstream-clean asymmetry, the .chdb namespace rationale, sync policy (re-run parity only when @clickhouse/client cuts a new release).

Test plan

• In-repo Connection contract suite green (15/15)
• @clickhouse/client integration suite via runner.mjs: 202 / 232 pass, 30 skipped with documented reasons in tests/clickhouse-js/skip_list.json
• Layer 1 v3 suite still passes (no regression on top of feat(l1): multi-connection model + async-stress timeout stabilization #51)
• npm run build clean (TypeScript enforces conformance to upstream Connection<Stream.Readable> via import type re-export)
• Reviewer to run node tests/clickhouse-js/runner.mjs locally

Skip categories (30 skips)

• HTTP transport (no socket / no headers / no compression / no keep-alive): 12 files
• Auth / RBAC / TLS: 5 files
• Server runtime / cluster topology: 2 files
• HTTP session / abort semantics: 3 files
• chdb engine gaps (JSONEachRowWithProgress, system.settings iteration): 2 files
• Per-test divergences (response_headers / stream decompression / chdb default-timezone / Float64 output precision): 6 entries

Each skip has a reason in skip_list.json.

Sync policy

chdb-node tests against the latest released version of @clickhouse/client. Only when @clickhouse/client cuts a new release does chdb-node re-run its parity job and update its blacklist for any newly-failing tests.

Generated with Claude Code
via Happy

[ShawnChen-Sirius]

@chibugai review it

[Copilot]

Pull request overview

Introduces a new chdb/connection public entrypoint that implements @clickhouse/client-common’s Connection<Stream.Readable> so chdb-node can plug into @clickhouse/client via createClient({ connection }), plus adds an upstream parity runner + CI workflow to validate compatibility.

Changes:

• Added src/connection/* with ChdbConnection, .chdb extension surface, and type re-exports from @clickhouse/client-common.
• Added a clickhouse-js parity runner (tests/clickhouse-js/*) with a skip manifest, plus a CI workflow to run contract + parity suites.
• Updated docs and package exports to publish the new chdb/connection subpath.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
vitest.config.ts	Externalizes index.js in vitest to avoid double-evaluation/global registry splits.
src/connection/index.ts	Public exports for the new chdb/connection surface.
src/connection/connection.ts	Re-exports @clickhouse/client-common Connection/result types; defines ChdbConnectionOptions.
src/connection/extension.ts	Defines .chdb extension namespace and binds it to a Layer 1 session.
src/connection/chdb-connection.ts	Implements ChdbConnection and createChdbConnection.
test/v3/connection/contract.test.ts	Adds an in-repo contract suite defining expected cross-backend invariants.
tests/clickhouse-js/runner.mjs	Adds a runner that clones/builds clickhouse-js and runs its integration suite with skips.
tests/clickhouse-js/skip_list.json	Authoritative skip manifest for upstream suite parity runs.
tests/clickhouse-js/README.md	Documents the parity runner workflow and skip policy.
tests/clickhouse-js/inject_setup.ts	Describes injected vitest setup for wrapping createClient with ChdbConnection.
README.md	Documents the new chdb/connection feature and links design docs.
docs/design/pluggable-connection.md	Design document for pluggable Connection + parity policy.
.github/workflows/connection.yml	Adds CI jobs for contract and parity suites.
package.json	Adds ./connection export and introduces @clickhouse/client-common.
package-lock.json	Lockfile updates for new dependencies/versioning.

Comments suppressed due to low confidence (1)

package.json:66

• src/connection/chdb-connection.ts imports parseError from @clickhouse/client-common at runtime, but the PR adds @clickhouse/client-common only as a devDependency. Consumers installing chdb in production may omit devDependencies, causing require('@clickhouse/client-common') to fail at runtime. This needs to be a regular dependency (and lockfile updated accordingly).

  "devDependencies": {
    "@clickhouse/client-common": "^1.22.0",
    "@types/node": "^20.14.0",
    "apache-arrow": "^21.1.0",
    "chai": "^4.5.0",
    "mocha": "^10.7.3",
    "node-gyp": "^9.3.1",
    "typescript": "^5.5.0",
    "vitest": "^2.0.0"
  },
  "dependencies": {
    "node-addon-api": "^6.1.0",
    "node-gyp-build": "^4.6.0"
  },

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.