feat(clickhouse-driver): Support passing custom HTTP headers (cube-js#11161)

Allow forwarding arbitrary HTTP headers on every request to ClickHouse, configured via the `headers` option in `driver_factory` (mirroring the Trino/Presto driver).

Author: ovr

docs-mintlify/admin/connect-to-data/data-sources/clickhouse.mdx

@@ -122,6 +122,80 @@ To enable SSL-encrypted connections between Cube and ClickHouse, set the
 configure custom certificates, please check out [Enable SSL Connections to the
 Database][ref-recipe-enable-ssl].
 
+## Custom headers
+
+The ClickHouse driver supports forwarding custom HTTP headers on every request to
+the ClickHouse server. This is useful when requests pass through a proxy or gateway
+that expects additional headers (e.g., for routing or tracing). See the [ClickHouse
+JavaScript client configuration][clickhouse-docs-js-config] for more details.
+
+Custom headers can't be configured via environment variables. Instead, use the
+[`driver_factory`](/reference/configuration/config#driver_factory) configuration
+option to pass a `headers` object to the driver:
+
+<CodeGroup>
+
+```python title="Python"
+from cube import config
+
+@config('driver_factory')
+def driver_factory(ctx: dict) -> dict:
+  return {
+    'type': 'clickhouse',
+    'headers': {
+      'X-Custom-Header': 'value',
+      'X-Routing-Group': 'analytics'
+    }
+  }
+```
+
+```javascript title="JavaScript"
+module.exports = {
+  driverFactory: ({ dataSource }) => ({
+    type: "clickhouse",
+    headers: {
+      "X-Custom-Header": "value",
+      "X-Routing-Group": "analytics"
+    }
+  })
+};
+```
+
+</CodeGroup>
+
+In multitenant deployments, you can use the [security
+context](/embedding/authentication/security-context) to pass per-tenant headers, for example
+to forward a user token from the API request down to ClickHouse:
+
+<CodeGroup>
+
+```python title="Python"
+from cube import config
+
+@config('driver_factory')
+def driver_factory(ctx: dict) -> dict:
+  security_context = ctx['securityContext']
+  return {
+    'type': 'clickhouse',
+    'headers': {
+      'X-Custom-User-Token': security_context['token']
+    }
+  }
+```
+
+```javascript title="JavaScript"
+module.exports = {
+  driverFactory: ({ securityContext }) => ({
+    type: "clickhouse",
+    headers: {
+      "X-Custom-User-Token": securityContext.token
+    }
+  })
+};
+```
+
+</CodeGroup>
+
 ## Additional Configuration
 
 You can connect to a ClickHouse database when your user's permissions are
@@ -134,6 +208,7 @@ You can connect to a ClickHouse database with compression enabled, by setting
 [clickhouse]: https://clickhouse.tech/
 [clickhouse-docs-users]:
   https://clickhouse.tech/docs/en/operations/settings/settings-users/
+[clickhouse-docs-js-config]: https://clickhouse.com/docs/integrations/javascript#configuration
 [clickhouse-readonly]: https://clickhouse.com/docs/en/operations/settings/permissions-for-queries#readonly
 [ref-caching-using-preaggs-build-strats]: /docs/pre-aggregations/using-pre-aggregations#pre-aggregation-build-strategies
 [ref-recipe-enable-ssl]: /recipes/configuration/using-ssl-connections-to-data-source

docs/content/product/configuration/data-sources/clickhouse.mdx

@@ -120,6 +120,44 @@ To enable SSL-encrypted connections between Cube and ClickHouse, set the
 configure custom certificates, please check out [Enable SSL Connections to the
 Database][ref-recipe-enable-ssl].
 
+## Custom headers
+
+The ClickHouse driver supports forwarding custom HTTP headers on every request to
+the ClickHouse server. This is useful when requests pass through a proxy or gateway
+that expects additional headers (e.g., for routing or tracing). See the [ClickHouse
+JavaScript client configuration][clickhouse-docs-js-config] for more details.
+
+Custom headers can't be configured via environment variables. Instead, use the
+[`driverFactory`][ref-config-driverfactory] configuration option to pass a `headers`
+object to the driver:
+
+```javascript
+module.exports = {
+  driverFactory: ({ dataSource }) => ({
+    type: "clickhouse",
+    headers: {
+      "X-Custom-Header": "value",
+      "X-Routing-Group": "analytics"
+    }
+  })
+};
+```
+
+In multitenant deployments, you can use the [security context][ref-sec-ctx] to pass
+per-tenant headers, for example to forward a user token from the API request down to
+ClickHouse:
+
+```javascript
+module.exports = {
+  driverFactory: ({ securityContext }) => ({
+    type: "clickhouse",
+    headers: {
+      "X-Custom-User-Token": securityContext.token
+    }
+  })
+};
+```
+
 ## Additional Configuration
 
 You can connect to a ClickHouse database when your user's permissions are
@@ -132,7 +170,10 @@ You can connect to a ClickHouse database with compression enabled, by setting
 [clickhouse]: https://clickhouse.tech/
 [clickhouse-docs-users]:
   https://clickhouse.tech/docs/en/operations/settings/settings-users/
+[clickhouse-docs-js-config]: https://clickhouse.com/docs/integrations/javascript#configuration
 [clickhouse-readonly]: https://clickhouse.com/docs/en/operations/settings/permissions-for-queries#readonly
+[ref-config-driverfactory]: /product/configuration/reference/config#driver_factory
+[ref-sec-ctx]: /product/auth/context
 [ref-caching-using-preaggs-build-strats]:
   /product/caching/using-pre-aggregations#pre-aggregation-build-strategies
 [ref-recipe-enable-ssl]:

packages/cubejs-clickhouse-driver/package.json

@@ -23,8 +23,9 @@
     "watch": "tsc -w",
     "lint": "eslint src/* test/* --ext .ts",
     "lint:fix": "eslint --fix src/* test/* --ext .ts",
-    "integration": "jest dist/test",
-    "integration:clickhouse": "jest dist/test"
+    "unit": "jest dist/test/unit",
+    "integration": "jest dist/test/integration",
+    "integration:clickhouse": "jest dist/test/integration"
   },
   "dependencies": {
     "@clickhouse/client": "^1.12.0",

packages/cubejs-clickhouse-driver/src/ClickHouseDriver.ts

@@ -95,6 +95,12 @@ export interface ClickHouseDriverOptions {
    * Whether this driver is used for pre-aggregations.
    */
   preAggregations?: boolean,
+
+  /**
+   * Custom HTTP headers attached to every request sent to ClickHouse.
+   * @see https://clickhouse.com/docs/integrations/javascript#configuration
+   */
+  headers?: Record<string, string>,
 }
 
 interface ClickhouseDriverExportRequiredAWS {
@@ -121,6 +127,7 @@ type ClickHouseDriverConfig = {
   exportBucket: ClickhouseDriverExportAWS | null,
   compression: { response?: boolean; request?: boolean },
   clickhouseSettings: ClickHouseSettings,
+  headers: Record<string, string>,
 };
 
 export class ClickHouseDriver extends BaseDriver implements DriverInterface {
@@ -188,6 +195,8 @@ export class ClickHouseDriver extends BaseDriver implements DriverInterface {
         // can not be changed
         ...(this.readOnlyMode ? {} : { join_use_nulls: 1 }),
       },
+      // Custom HTTP headers can only be passed via driver_factory, not env vars.
+      headers: config.headers ?? {},
     };
 
     const maxPoolSize = config.maxPoolSize ?? getEnv('dbMaxPoolSize', { dataSource, preAggregations }) ?? 8;
@@ -245,6 +254,7 @@ export class ClickHouseDriver extends BaseDriver implements DriverInterface {
       clickhouse_settings: this.config.clickhouseSettings,
       request_timeout: this.config.requestTimeout,
       max_open_connections: maxPoolSize,
+      http_headers: this.config.headers,
     });
   }
 

…use-driver/test/ClickHouseDriver.test.ts …est/integration/ClickHouseDriver.test.tspackages/cubejs-clickhouse-driver/test/ClickHouseDriver.test.ts renamed to packages/cubejs-clickhouse-driver/test/integration/ClickHouseDriver.test.ts packages/cubejs-clickhouse-driver/test/ClickHouseDriver.test.ts renamed to packages/cubejs-clickhouse-driver/test/integration/ClickHouseDriver.test.ts

@@ -1,8 +1,8 @@
 import { ClickhouseDBRunner } from '@cubejs-backend/testing-shared';
 import { streamToArray } from '@cubejs-backend/shared';
 
-import { ClickHouseDriver } from '../src';
-import type { ClickHouseDriverOptions } from '../src';
+import { ClickHouseDriver } from '../../src';
+import type { ClickHouseDriverOptions } from '../../src';
 
 describe('ClickHouseDriver', () => {
   jest.setTimeout(20 * 1000);

packages/cubejs-clickhouse-driver/test/unit/headers.test.ts

@@ -0,0 +1,46 @@
+import { createClient } from '@clickhouse/client';
+
+import { ClickHouseDriver } from '../../src';
+
+jest.mock('@clickhouse/client', () => ({
+  createClient: jest.fn(() => ({
+    close: jest.fn(),
+  })),
+}));
+
+const createClientMock = createClient as unknown as jest.Mock;
+
+describe('ClickHouseDriver custom headers', () => {
+  beforeEach(() => {
+    createClientMock.mockClear();
+  });
+
+  it('forwards custom headers to the underlying client as http_headers', () => {
+    const headers = {
+      'X-Custom-Header': 'custom-value',
+    };
+
+    // eslint-disable-next-line no-new
+    new ClickHouseDriver({
+      host: 'localhost',
+      port: '8123',
+      dataSource: 'default',
+      headers,
+    });
+
+    expect(createClientMock).toHaveBeenCalled();
+    expect(createClientMock.mock.calls[0][0]).toMatchObject({ http_headers: headers });
+  });
+
+  it('defaults http_headers to an empty object when no headers are configured', () => {
+    // eslint-disable-next-line no-new
+    new ClickHouseDriver({
+      host: 'localhost',
+      port: '8123',
+      dataSource: 'default',
+    });
+
+    expect(createClientMock).toHaveBeenCalled();
+    expect(createClientMock.mock.calls[0][0]).toMatchObject({ http_headers: {} });
+  });
+});