refactor: decouple clickhouse client into browser.ts and node.ts (#1119)

wrn14897 · web-flow · commit aacd24dde625 · 2025-08-29T16:40:28.000Z
- Fixed the issue where the @clickhouse/client module wasn’t bundled. It’s also cleaner to keep non-shared methods decoupled between node and browser environments
- Bumped the default request timeout to 1hr

Ref: HDX-2294
diff --git a/.changeset/modern-coats-exercise.md b/.changeset/modern-coats-exercise.md
@@ -0,0 +1,7 @@
+---
+"@hyperdx/common-utils": patch
+"@hyperdx/api": patch
+"@hyperdx/app": patch
+---
+
+refactor: decouple clickhouse client into browser.ts and node.ts
diff --git a/.changeset/popular-geese-sin.md b/.changeset/popular-geese-sin.md
@@ -0,0 +1,7 @@
+---
+"@hyperdx/common-utils": patch
+"@hyperdx/api": patch
+"@hyperdx/app": patch
+---
+
+bump: default request_timeout to 1hr
diff --git a/packages/api/src/clickhouse/__tests__/renderChartConfig.test.ts b/packages/api/src/clickhouse/__tests__/renderChartConfig.test.ts
@@ -1,6 +1,7 @@
 // TODO: we might want to move this test file to common-utils package
 
-import { ChSql, ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse';
+import { ChSql } from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import { getMetadata } from '@hyperdx/common-utils/dist/metadata';
 import { renderChartConfig } from '@hyperdx/common-utils/dist/renderChartConfig';
 import {
diff --git a/packages/api/src/fixtures.ts b/packages/api/src/fixtures.ts
@@ -1,4 +1,4 @@
-import { getJSNativeCreateClient } from '@hyperdx/common-utils/dist/clickhouse';
+import { createNativeClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import {
   DisplayType,
   SavedChartConfig,
@@ -38,8 +38,7 @@ let clickhouseClient: any;
 
 const getClickhouseClient = async () => {
   if (!clickhouseClient) {
-    const createClient = await getJSNativeCreateClient();
-    clickhouseClient = createClient({
+    clickhouseClient = createNativeClient({
       url: config.CLICKHOUSE_HOST,
       username: config.CLICKHOUSE_USER,
       password: config.CLICKHOUSE_PASSWORD,
diff --git a/packages/api/src/routers/external-api/__tests__/charts.test.ts b/packages/api/src/routers/external-api/__tests__/charts.test.ts
@@ -1,4 +1,4 @@
-import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import { SourceKind } from '@hyperdx/common-utils/dist/types';
 import { MetricsDataType } from '@hyperdx/common-utils/dist/types';
 import { ObjectId } from 'mongodb';
diff --git a/packages/api/src/routers/external-api/v2/charts.ts b/packages/api/src/routers/external-api/v2/charts.ts
@@ -1,4 +1,4 @@
-import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import { getMetadata } from '@hyperdx/common-utils/dist/metadata';
 import {
   ChartConfigWithOptDateRange,
diff --git a/packages/api/src/tasks/__tests__/checkAlerts.test.ts b/packages/api/src/tasks/__tests__/checkAlerts.test.ts
@@ -1,4 +1,4 @@
-import * as clickhouse from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import mongoose from 'mongoose';
 import ms from 'ms';
 
@@ -725,7 +725,7 @@ describe('checkAlerts', () => {
         savedSearch,
       };
 
-      const clickhouseClient = new clickhouse.ClickhouseClient({
+      const clickhouseClient = new ClickhouseClient({
         host: connection.host,
         username: connection.username,
         password: connection.password,
@@ -965,7 +965,7 @@ describe('checkAlerts', () => {
         dashboard,
       };
 
-      const clickhouseClient = new clickhouse.ClickhouseClient({
+      const clickhouseClient = new ClickhouseClient({
         host: connection.host,
         username: connection.username,
         password: connection.password,
@@ -1195,7 +1195,7 @@ describe('checkAlerts', () => {
         dashboard,
       };
 
-      const clickhouseClient = new clickhouse.ClickhouseClient({
+      const clickhouseClient = new ClickhouseClient({
         host: connection.host,
         username: connection.username,
         password: connection.password,
@@ -1404,7 +1404,7 @@ describe('checkAlerts', () => {
         dashboard,
       };
 
-      const clickhouseClient = new clickhouse.ClickhouseClient({
+      const clickhouseClient = new ClickhouseClient({
         host: connection.host,
         username: connection.username,
         password: connection.password,
diff --git a/packages/api/src/tasks/__tests__/singleInvocationAlert.test.ts b/packages/api/src/tasks/__tests__/singleInvocationAlert.test.ts
@@ -1,4 +1,4 @@
-import * as clickhouse from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import { createServer } from 'http';
 import mongoose from 'mongoose';
 import ms from 'ms';
@@ -188,7 +188,7 @@ describe('Single Invocation Alert Test', () => {
       taskType: AlertTaskType.SAVED_SEARCH,
       savedSearch,
     };
-    const clickhouseClient = new clickhouse.ClickhouseClient({
+    const clickhouseClient = new ClickhouseClient({
       host: connection.host,
       username: connection.username,
       password: connection.password,
@@ -404,7 +404,7 @@ describe('Single Invocation Alert Test', () => {
       dashboard,
     };
 
-    const clickhouseClient = new clickhouse.ClickhouseClient({
+    const clickhouseClient = new ClickhouseClient({
       host: connection.host,
       username: connection.username,
       password: connection.password,
diff --git a/packages/api/src/tasks/checkAlerts.ts b/packages/api/src/tasks/checkAlerts.ts
@@ -3,6 +3,7 @@
 // --------------------------------------------------------
 import PQueue from '@esm2cjs/p-queue';
 import * as clickhouse from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import { getMetadata, Metadata } from '@hyperdx/common-utils/dist/metadata';
 import {
   ChartConfigWithOptDateRange,
@@ -67,7 +68,7 @@ const fireChannelEvent = async ({
   alert: IAlert;
   alertProvider: AlertProvider;
   attributes: Record<string, string>; // TODO: support other types than string
-  clickhouseClient: clickhouse.ClickhouseClient;
+  clickhouseClient: ClickhouseClient;
   dashboard?: IDashboard | null;
   endTime: Date;
   group?: string;
@@ -138,7 +139,7 @@ const fireChannelEvent = async ({
 export const processAlert = async (
   now: Date,
   details: AlertDetails,
-  clickhouseClient: clickhouse.ClickhouseClient,
+  clickhouseClient: ClickhouseClient,
   connectionId: string,
   alertProvider: AlertProvider,
 ) => {
@@ -397,7 +398,7 @@ export default class CheckAlertTask implements HdxTask<CheckAlertsTaskArgs> {
       });
     }
 
-    const clickhouseClient = new clickhouse.ClickhouseClient({
+    const clickhouseClient = new ClickhouseClient({
       host: conn.host,
       username: conn.username,
       password: conn.password,
diff --git a/packages/api/src/tasks/template.ts b/packages/api/src/tasks/template.ts
@@ -1,4 +1,5 @@
 import * as clickhouse from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import { Metadata } from '@hyperdx/common-utils/dist/metadata';
 import { renderChartConfig } from '@hyperdx/common-utils/dist/renderChartConfig';
 import {
@@ -357,7 +358,7 @@ export const renderAlertTemplate = async ({
   team,
 }: {
   alertProvider: AlertProvider;
-  clickhouseClient: clickhouse.ClickhouseClient;
+  clickhouseClient: ClickhouseClient;
   metadata: Metadata;
   template?: string | null;
   title: string;
diff --git a/packages/api/src/tasks/usageStats.ts b/packages/api/src/tasks/usageStats.ts
@@ -1,7 +1,5 @@
-import {
-  ClickhouseClient,
-  ResponseJSON,
-} from '@hyperdx/common-utils/dist/clickhouse';
+import { ResponseJSON } from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import { MetricsDataType, SourceKind } from '@hyperdx/common-utils/dist/types';
 import * as HyperDX from '@hyperdx/node-opentelemetry';
 import ms from 'ms';
diff --git a/packages/app/src/clickhouse.ts b/packages/app/src/clickhouse.ts
@@ -7,10 +7,10 @@
 
 import {
   chSql,
-  ClickhouseClient,
   ColumnMeta,
   ResponseJSON,
 } from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/browser';
 import { useQuery, UseQueryOptions } from '@tanstack/react-query';
 
 import { IS_LOCAL_MODE } from '@/config';
diff --git a/packages/app/src/components/ConnectionForm.tsx b/packages/app/src/components/ConnectionForm.tsx
@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useState } from 'react';
 import { useForm } from 'react-hook-form';
-import { testLocalConnection } from '@hyperdx/common-utils/dist/clickhouse';
+import { testLocalConnection } from '@hyperdx/common-utils/dist/clickhouse/browser';
 import { Connection } from '@hyperdx/common-utils/dist/types';
 import { Box, Button, Flex, Group, Stack, Text, Tooltip } from '@mantine/core';
 import { notifications } from '@mantine/notifications';
diff --git a/packages/app/src/connection.ts b/packages/app/src/connection.ts
@@ -1,5 +1,5 @@
 import store from 'store2';
-import { testLocalConnection } from '@hyperdx/common-utils/dist/clickhouse';
+import { testLocalConnection } from '@hyperdx/common-utils/dist/clickhouse/browser';
 import { Connection } from '@hyperdx/common-utils/dist/types';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 
diff --git a/packages/app/src/hooks/__tests__/useMetadata.test.tsx b/packages/app/src/hooks/__tests__/useMetadata.test.tsx
@@ -1,6 +1,6 @@
 import React from 'react';
 import * as metadataModule from '@hyperdx/app/src/metadata';
-import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse';
+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/browser';
 import { Metadata, MetadataCache } from '@hyperdx/common-utils/dist/metadata';
 import { ChartConfigWithDateRange } from '@hyperdx/common-utils/dist/types';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
diff --git a/packages/common-utils/src/__tests__/metadata.test.ts b/packages/common-utils/src/__tests__/metadata.test.ts
@@ -1,4 +1,4 @@
-import { ClickhouseClient } from '../clickhouse';
+import { ClickhouseClient } from '../clickhouse/node';
 import { Metadata, MetadataCache } from '../metadata';
 import * as renderChartConfigModule from '../renderChartConfig';
 import { ChartConfigWithDateRange } from '../types';
diff --git a/packages/common-utils/src/__tests__/queryParser.test.ts b/packages/common-utils/src/__tests__/queryParser.test.ts
@@ -1,4 +1,4 @@
-import { ClickhouseClient } from '@/clickhouse';
+import { ClickhouseClient } from '@/clickhouse/node';
 import { getMetadata } from '@/metadata';
 import { CustomSchemaSQLSerializerV2 } from '@/queryParser';
 
diff --git a/packages/common-utils/src/clickhouse/browser.ts b/packages/common-utils/src/clickhouse/browser.ts
@@ -0,0 +1,145 @@
+import type {
+  BaseResultSet,
+  ClickHouseSettings,
+  DataFormat,
+} from '@clickhouse/client-common';
+import { createClient } from '@clickhouse/client-web';
+
+import {
+  BaseClickhouseClient,
+  ClickhouseClientOptions,
+  parameterizedQueryToSql,
+  QueryInputs,
+} from './index';
+
+const localModeFetch: typeof fetch = (input, init) => {
+  if (!init) init = {};
+  const url = new URL(
+    input instanceof URL ? input : input instanceof Request ? input.url : input,
+  );
+
+  // CORS is unhappy with the authorization header, so we will supply as query params instead
+  const auth: string = init.headers?.['Authorization'];
+  const [username, password] = window
+    .atob(auth.substring('Bearer'.length))
+    .split(':');
+  delete init.headers?.['Authorization'];
+  delete init.headers?.['authorization'];
+  if (username) url.searchParams.set('user', username);
+  if (password) url.searchParams.set('password', password);
+
+  return fetch(`${url.toString()}`, init);
+};
+
+const standardModeFetch: typeof fetch = (input, init) => {
+  if (!init) init = {};
+  // authorization is handled on the backend, don't send this header
+  delete init.headers?.['Authorization'];
+  delete init.headers?.['authorization'];
+  return fetch(input, init);
+};
+
+export const testLocalConnection = async ({
+  host,
+  username,
+  password,
+}: {
+  host: string;
+  username: string;
+  password: string;
+}): Promise<boolean> => {
+  try {
+    const client = new ClickhouseClient({ host, username, password });
+    const result = await client.query({
+      query: 'SELECT 1',
+      format: 'TabSeparatedRaw',
+    });
+    return result.text().then(text => text.trim() === '1');
+  } catch (e) {
+    console.warn('Failed to test local connection', e);
+    return false;
+  }
+};
+
+export class ClickhouseClient extends BaseClickhouseClient {
+  constructor(options: ClickhouseClientOptions) {
+    super(options);
+  }
+
+  protected async __query<Format extends DataFormat>({
+    query,
+    format = 'JSON' as Format,
+    query_params = {},
+    abort_signal,
+    clickhouse_settings: external_clickhouse_settings,
+    connectionId,
+    queryId,
+  }: QueryInputs<Format>): Promise<BaseResultSet<ReadableStream, Format>> {
+    let debugSql = '';
+    try {
+      debugSql = parameterizedQueryToSql({ sql: query, params: query_params });
+    } catch (e) {
+      debugSql = query;
+    }
+    let _url = this.host;
+
+    // eslint-disable-next-line no-console
+    console.log('--------------------------------------------------------');
+    // eslint-disable-next-line no-console
+    console.log('Sending Query:', debugSql);
+    // eslint-disable-next-line no-console
+    console.log('--------------------------------------------------------');
+
+    let clickhouse_settings = structuredClone(
+      external_clickhouse_settings || {},
+    );
+    if (clickhouse_settings?.max_rows_to_read && this.maxRowReadOnly) {
+      delete clickhouse_settings['max_rows_to_read'];
+    }
+
+    clickhouse_settings = {
+      date_time_output_format: 'iso',
+      wait_end_of_query: 0,
+      cancel_http_readonly_queries_on_client_close: 1,
+      ...clickhouse_settings,
+    };
+    const http_headers: { [header: string]: string } = {
+      ...(connectionId && connectionId !== 'local'
+        ? { 'x-hyperdx-connection-id': connectionId }
+        : {}),
+    };
+    let myFetch: typeof fetch;
+    const isLocalMode = this.username != null && this.password != null;
+    if (isLocalMode) {
+      myFetch = localModeFetch;
+      clickhouse_settings.add_http_cors_header = 1;
+    } else {
+      _url = `${window.origin}${this.host}`; // this.host is just a pathname in this scenario
+      myFetch = standardModeFetch;
+    }
+
+    const url = new URL(_url);
+    const clickhouseClient = createClient({
+      url: url.origin,
+      pathname: url.pathname,
+      http_headers,
+      clickhouse_settings,
+      username: this.username ?? '',
+      password: this.password ?? '',
+      // Disable keep-alive to prevent multiple concurrent dashboard requests from exceeding the 64KB payload size limit.
+      keep_alive: {
+        enabled: false,
+      },
+      fetch: myFetch,
+      request_timeout: this.requestTimeout,
+    });
+    return clickhouseClient.query({
+      query,
+      query_params,
+      format,
+      abort_signal,
+      clickhouse_settings,
+      query_id: queryId,
+    }) as Promise<BaseResultSet<ReadableStream, Format>>;
+  }
+}
diff --git a/packages/common-utils/src/clickhouse/index.ts b/packages/common-utils/src/clickhouse/index.ts
diff --git a/packages/common-utils/src/clickhouse/node.ts b/packages/common-utils/src/clickhouse/node.ts
diff --git a/packages/common-utils/src/metadata.ts b/packages/common-utils/src/metadata.ts

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse';`
	`1`	`+import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';`
`2`	`2`	`import { SourceKind } from '@hyperdx/common-utils/dist/types';`
`3`	`3`	`import { MetricsDataType } from '@hyperdx/common-utils/dist/types';`
`4`	`4`	`import { ObjectId } from 'mongodb';`