Skip to content

feat(clickhouse-driver): support client TLS certificates#11107

Open
PaulVrugt wants to merge 2 commits into
cube-js:masterfrom
PaulVrugt:feat/clickhouse-driver-tls
Open

feat(clickhouse-driver): support client TLS certificates#11107
PaulVrugt wants to merge 2 commits into
cube-js:masterfrom
PaulVrugt:feat/clickhouse-driver-tls

Conversation

@PaulVrugt

Copy link
Copy Markdown

Description

Adds TLS support to the ClickHouse driver, including mutual TLS (client
certificate authentication) when connecting over HTTPS.

Motivation: a multi-tenant deployment where tenant isolation is enforced in
ClickHouse via distinct per-tenant users (each created with
IDENTIFIED WITH ssl_certificate) and row policies. Cube must connect as a
different ClickHouse user per tenant, authenticated by a per-tenant client
certificate rather than a shared password. The underlying @clickhouse/client
already supports a tls: { ca_cert, cert, key } option; the Cube driver simply
did not forward any certificate material.

Changes

  • Read CA, client certificate and key from the standard
    CUBEJS_DB_SSL_CA / CUBEJS_DB_SSL_CERT / CUBEJS_DB_SSL_KEY environment
    variables (already parsed by BaseDriver.getSslOptions, with file-path
    support) and map them to the @clickhouse/client tls option.
  • Add an ssl: { ca, cert, key } option to ClickHouseDriverOptions so
    certificate material can be supplied programmatically from a driverFactory
    (e.g. per-tenant client certificates loaded from a secret store). Mutual TLS
    is enabled when ca, cert and key are all present; ca alone enables
    basic TLS.
  • Connect over HTTPS automatically when TLS material is configured.
  • Document the new options on the ClickHouse data-source page.
  • Add unit tests covering the option → tls mapping (env vars, programmatic
    ssl, basic vs mutual, Buffer/string inputs, precedence).

No new dependencies — @clickhouse/client is already a direct dependency and
natively supports these options.

Checklist

  • Tests run
  • Linter run
  • Tests added — unit tests for the TLS option mapping
  • Docs updated

Notes for reviewers

  • The added unit tests do not need a running ClickHouse instance (the client
    connects lazily). A full integration test for mutual TLS would require a
    TLS-enabled ClickHouse container (server cert + CA + an ssl_certificate
    user) and an extension of ClickhouseDBRunner in testing-shared. I'm happy
    to add that — I'd appreciate guidance on how you'd prefer the TLS test harness
    shaped before investing in it.
  • I was unable to run the full monorepo yarn build / yarn lint /
    integration:clickhouse locally; please confirm CI is green.

Add TLS support to the ClickHouse driver, including mutual TLS (client
certificate authentication) for connecting over HTTPS.

- Read CA, client certificate and key from the standard
  CUBEJS_DB_SSL_CA / CUBEJS_DB_SSL_CERT / CUBEJS_DB_SSL_KEY environment
  variables (parsed by BaseDriver.getSslOptions, with file-path support)
  and map them to the @clickhouse/client `tls` option.
- Add an `ssl: { ca, cert, key }` option to ClickHouseDriverOptions so
  certificate material can be supplied programmatically from a
  driverFactory (for example, per-tenant client certificates). Mutual TLS
  is enabled when ca, cert and key are all present.
- Connect over HTTPS automatically when TLS material is configured.
- Document the new options and add unit tests for the option mapping.

Signed-off-by: Paul Vrugt <paulvrugt@gmail.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@PaulVrugt PaulVrugt requested review from a team and keydunov as code owners June 17, 2026 15:23
@github-actions github-actions Bot added driver:clickhouse Issues related to the ClickHouse driver javascript Pull requests that update Javascript code data source driver pr:community Contribution from Cube.js community members. labels Jun 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

data source driver driver:clickhouse Issues related to the ClickHouse driver javascript Pull requests that update Javascript code pr:community Contribution from Cube.js community members.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant