Skip to content

Keep pluggable connection as a narrow internal chDB experiment (follow-up to #879) - #880

Merged
peter-leonov-ch merged 4 commits into
mainfrom
pluggable-connection-follow-up
Jun 23, 2026
Merged

peter-leonov-ch merged 4 commits into
mainfrom
pluggable-connection-follow-up

Conversation

@peter-leonov-ch

@peter-leonov-ch peter-leonov-ch commented Jun 23, 2026 •

Copy link
Copy Markdown
Collaborator

What this does

A small follow-up to #879. It dials the pluggable connection option back from a public plugin surface to a deliberately narrow, internal @experimental hook whose only intended consumer today is the chDB integration.

Concretely:

  • Removes the public re-exports of the Connection<Stream> contract (Connection, ConnBaseQueryParams, ConnQueryResult, ConnInsertParams, ConnPingResult, ClickHouseSummary, …) from the @clickhouse/client (Node) entrypoint.
  • Deletes docs/design/pluggable-connection.md, which described a fuller pluggable-backend system we are intentionally not committing to yet.
  • Trims the CHANGELOG and connection? JSDoc to state plainly that the field exists to unblock chDB and may change.
  • Moves the rationale into the connection? JSDoc itself, so it lives right where anyone touching the field will read it.

The runtime behavior is unchanged: the make_connection factory override still works exactly as merged in #879. This is purely a framing/surface-area change.

Why

Two pressures, gently in tension:

  1. We genuinely want to unblock chDB (chdb-io/chdb-node#52) with an in-process backend, today.
  2. We do not want to turn the Node client into the common package replacement — a public pluggable-backend framework implies a stable third-party contract and invites a second client family mirroring the entire public API, which is a real long-term maintenance burden.

Keeping the Connection types out of the public entrypoint is what enforces this distinction. A backend has to deep-import or structurally match the shape — and that small friction is by design: it signals "unsupported, may change" rather than promising an API we are not ready to own. Nothing internal depends on the re-exports (internal code imports these types from ./common), and npm run typecheck passes.

Next steps (not in this PR)

  1. Verify it works and is actually needed in production with the real chDB backend before hardening anything.
  2. If validated, build a specialized client that drops the HTTP connection-pooling burden entirely and leans into the in-process transport — leaving the higher-level query API as the surface we invest in and improve, rather than retrofitting it onto the HTTP-shaped client.

Feedback very welcome — this is intentionally the smallest step that unblocks chDB while keeping our options open.

peter-leonov-ch and others added 2 commits June 23, 2026 10:17
let's not make this into a plugin system yet, keeping as an experiment
…xperiment

Move the rationale into the `connection?` JSDoc: it is a deliberately
narrow, experimental hook to unblock the chDB integration, not a public
pluggable-backend system. Explains why the `Connection` contract is not
re-exported from the package entrypoint (deep-import friction is by design).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings June 23, 2026 08:34
@codecov

codecov Bot commented Jun 23, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR narrows the previously-introduced pluggable connection injection point to a deliberately small @experimental hook intended for the chDB integration, reducing the implied long-term public plugin surface.

Changes:

  • Removed public entrypoint re-exports of the low-level Connection<Stream> contract types from @clickhouse/client (Node).
  • Updated the connection?: ... option JSDoc and trimmed the corresponding CHANGELOG entry to emphasize the chDB-focused experimental intent.
  • Deleted the design doc that described a broader pluggable-backend system (docs/design/pluggable-connection.md).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
packages/client-node/src/index.ts Removes public re-exports of the Connection/Conn* contract types from the Node package entrypoint.
packages/client-node/src/config.ts Reframes the connection? option JSDoc as a narrow internal experiment and links to chDB context.
packages/client-node/src/client.ts Adjusts inline comments to match the narrowed “chDB-only experimental” framing.
docs/design/pluggable-connection.md Deletes the broader pluggable-connection design document.
CHANGELOG.md Trims the previously-added feature note for connection?, but currently under-documents the export-surface change.

Comment thread packages/client-node/src/config.ts Resolved
Comment thread packages/client-node/src/config.ts Resolved
Comment thread CHANGELOG.md Resolved
peter-leonov-ch and others added 2 commits June 23, 2026 10:41
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Addresses PR #880 review: the connection JSDoc described the Connection
contract as "public", which contradicts this PR's intent — it is
intentionally not re-exported from the package entrypoint.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@peter-leonov-ch
peter-leonov-ch merged commit 274844f into main Jun 23, 2026
70 checks passed
@peter-leonov-ch
peter-leonov-ch deleted the pluggable-connection-follow-up branch June 23, 2026 10:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants