chore: upgrade ClickHouse to 26.10 (#3624)

## Summary

Upgrades ClickHouse from 26.8.36.3 to 26.10.3.7 and updates the tests that assumed the 26.8 TimeSeries layout. Needed for PromQL label lookups through ClickHouse's Prometheus HTTP API (26.9+).

- Pins `26.10.3.7` in the four compose files (incl. e2e) and the all-in-one `Dockerfile`.
- `metadata.int.test.ts`: pins the `getTimeSeriesTableColumns` tables to `version = 7` (26.10 defaults to version 8, which moves `min_time`/`max_time` out of the tags table), expects the renamed `metric_family` column, and adds `getTimeSeriesTableVersion` coverage.
- `timeseriesEngine.int.test.ts`: the version 8 suite fails instead of silently skipping.
- `seed-clickhouse.ts`: the e2e PromQL seed writes to `samples` (new tables have no `time_series` column).

No production code changes were needed. On an existing volume, `system.metric_log` history moves to `system.metric_log_0`. Local otel smoke tests need `clickhouse-client` 26.9+.

### References

- Linear Issue: part of HDX-5420

Author: karl-power

.changeset/upgrade-clickhouse-26-10.md

@@ -0,0 +1,11 @@
+---
+'@hyperdx/api': minor
+---
+
+chore: upgrade bundled ClickHouse to 26.10.3.7
+
+The all-in-one image and the Docker Compose files now use
+`clickhouse/clickhouse-server:26.10.3.7-alpine`. New TimeSeries tables default
+to schema version 8, which keeps each series' time range in a separate inner
+table; existing tables keep their layout. `system.metric_log` switches to the
+bucketed schema, and rows from before the upgrade move to `system.metric_log_0`.

docker-compose.ci.yml

@@ -22,7 +22,7 @@ services:
     depends_on:
       - ch-server
   ch-server:
-    image: clickhouse/clickhouse-server:26.8.36.3-alpine
+    image: clickhouse/clickhouse-server:26.10.3.7-alpine
     environment:
       # default settings
       CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1

docker-compose.dev.yml

@@ -112,7 +112,7 @@ services:
       hdx.dev.service: clickhouse
       hdx.dev.port: '${HDX_DEV_CH_HTTP_PORT:-8123}'
       hdx.dev.url: 'http://localhost:${HDX_DEV_CH_HTTP_PORT:-8123}'
-    image: clickhouse/clickhouse-server:26.8.36.3-alpine
+    image: clickhouse/clickhouse-server:26.10.3.7-alpine
     ports:
       - '${HDX_DEV_CH_HTTP_PORT:-8123}:8123' # http api
       - '${HDX_DEV_CH_NATIVE_PORT:-9000}:9000' # native

docker-compose.yml

@@ -109,7 +109,7 @@ services:
       - ch-server
       - db
   ch-server:
-    image: clickhouse/clickhouse-server:26.8.36.3-alpine
+    image: clickhouse/clickhouse-server:26.10.3.7-alpine
     # WARNING: Exposing the database port will make it accessible from outside the container,
     # potentially allowing unauthorized access. If you uncomment the ports below,
     # ensure to secure your database (e.g., with strong authentication, proper network rules, and firewalls).

docker/hyperdx/Dockerfile

@@ -8,7 +8,7 @@
 # - Otel Collector (otelcol)
 
 ARG NODE_VERSION=22.23.4
-ARG CLICKHOUSE_VERSION=26.8.36.3
+ARG CLICKHOUSE_VERSION=26.10.3.7
 ARG OTEL_COLLECTOR_VERSION=0.155.0
 ARG OTEL_COLLECTOR_CORE_VERSION=1.61.0
 

packages/api/src/controllers/__tests__/timeseriesEngine.int.test.ts

@@ -505,13 +505,10 @@ describe('timeseriesEngine controller', () => {
   });
 
   // Schema version 8 (the default from ClickHouse 26.10) moved min_time and
-  // max_time out of the tags table into a separate time ranges table. Older
-  // servers don't know the `version` setting, so these run only where the
-  // table can be created.
+  // max_time out of the tags table into a separate time ranges table.
   describe('table of schema version 8 (time ranges table)', () => {
     const V8_TABLE = 'test_ts_label_values_v8';
     const V8_NO_RANGES_TABLE = 'test_ts_label_values_v8_no_ranges';
-    let supported = true;
 
     const v8LabelValues = (
       args: Partial<Parameters<typeof queryLabelValues>[0]> & {
@@ -520,23 +517,18 @@ describe('timeseriesEngine controller', () => {
     ) => labelValues({ tableName: V8_TABLE, ...args });
 
     beforeAll(async () => {
-      try {
-        await seedTimeSeriesTagsTable({
-          table: V8_TABLE,
-          series: SERIES,
-          withSamples: true,
-          timeRanges: true,
-        });
-        await seedTimeSeriesTagsTable({
-          table: V8_NO_RANGES_TABLE,
-          series: SERIES,
-          storeTimeBounds: false,
-          timeRanges: true,
-        });
-      } catch (e) {
-        if (!/Unknown setting 'version'/.test(String(e))) throw e;
-        supported = false;
-      }
+      await seedTimeSeriesTagsTable({
+        table: V8_TABLE,
+        series: SERIES,
+        withSamples: true,
+        timeRanges: true,
+      });
+      await seedTimeSeriesTagsTable({
+        table: V8_NO_RANGES_TABLE,
+        series: SERIES,
+        storeTimeBounds: false,
+        timeRanges: true,
+      });
     });
 
     afterAll(async () => {
@@ -546,7 +538,6 @@ describe('timeseriesEngine controller', () => {
     });
 
     it('scopes label values to the window through the time ranges table', async () => {
-      if (!supported) return;
       expect(
         await v8LabelValues({
           labelName: 'job',
@@ -557,7 +548,6 @@ describe('timeseriesEngine controller', () => {
     });
 
     it('applies lone bounds against the time ranges', async () => {
-      if (!supported) return;
       expect(
         await v8LabelValues({
           labelName: '__name__',
@@ -573,7 +563,6 @@ describe('timeseriesEngine controller', () => {
     });
 
     it('returns nothing for a window no series covers', async () => {
-      if (!supported) return;
       expect(
         await v8LabelValues({
           labelName: '__name__',
@@ -584,7 +573,6 @@ describe('timeseriesEngine controller', () => {
     });
 
     it('evaluates match[] and narrows it by the window', async () => {
-      if (!supported) return;
       expect(
         await v8LabelValues({
           labelName: 'job',
@@ -602,7 +590,6 @@ describe('timeseriesEngine controller', () => {
     });
 
     it('scopes label names to the window and the selector', async () => {
-      if (!supported) return;
       const names = (
         args: Partial<Parameters<typeof queryLabelNames>[0]> = {},
       ) =>
@@ -627,7 +614,6 @@ describe('timeseriesEngine controller', () => {
     });
 
     it('rejects match[] without a time ranges table, and ignores the bounds', async () => {
-      if (!supported) return;
       await expect(
         labelValues({
           tableName: V8_NO_RANGES_TABLE,

packages/app/tests/e2e/docker-compose.yml

@@ -15,7 +15,7 @@ services:
           memory: 512M
           cpus: '0.5'
   ch-server:
-    image: clickhouse/clickhouse-server:26.8.36.3-alpine
+    image: clickhouse/clickhouse-server:26.10.3.7-alpine
     ports:
       - ${HDX_E2E_CH_PORT:-20500}:8123 # http api
       - ${HDX_E2E_CH_NATIVE_PORT:-20600}:9000 # native

packages/app/tests/e2e/seed-clickhouse.ts

@@ -1175,7 +1175,7 @@ async function insertPromqlMetric(
     .join('\n    UNION ALL\n    ');
 
   await client.query(`
-    INSERT INTO ${table} (metric_name, tags, time_series)
+    INSERT INTO ${table} (metric_name, tags, samples)
     ${rows}
   `);
 }

packages/common-utils/src/__tests__/metadata.int.test.ts

@@ -1159,14 +1159,17 @@ describe('Metadata Integration Tests', () => {
         clickhouse_settings: { allow_experimental_time_series_table: 1 },
       });
 
+    // Pinned to version 7: from version 8 (the default since ClickHouse 26.10)
+    // min_time/max_time live in a separate time ranges table, and
+    // store_min_time_and_max_time is rejected.
     beforeAll(async () => {
       await timeSeriesCommand(`DROP TABLE IF EXISTS default.${boundedTable}`);
       await timeSeriesCommand(`DROP TABLE IF EXISTS default.${unboundedTable}`);
       await timeSeriesCommand(
-        `CREATE TABLE default.${boundedTable} ENGINE = TimeSeries`,
+        `CREATE TABLE default.${boundedTable} ENGINE = TimeSeries SETTINGS version = 7`,
       );
       await timeSeriesCommand(
-        `CREATE TABLE default.${unboundedTable} ENGINE = TimeSeries SETTINGS store_min_time_and_max_time = 0`,
+        `CREATE TABLE default.${unboundedTable} ENGINE = TimeSeries SETTINGS store_min_time_and_max_time = 0, version = 7`,
       );
     });
 
@@ -1219,7 +1222,7 @@ describe('Metadata Integration Tests', () => {
     });
 
     it.each([
-      ['Metrics', ['metric_family_name', 'type', 'unit', 'help']],
+      ['Metrics', ['metric_family', 'type', 'unit', 'help']],
       ['Data', ['id', 'timestamp', 'value']],
     ] as const)(
       'describes the %s inner table',
@@ -1307,6 +1310,50 @@ describe('Metadata Integration Tests', () => {
     });
   });
 
+  // The version decides which samples column a query reads (`samples` from
+  // version 3, `time_series` before), so a version read as 0 silently breaks
+  // queries on new tables.
+  describe('getTimeSeriesTableVersion', () => {
+    const defaultTable = 'test_ts_version_default';
+    const v7Table = 'test_ts_version_7';
+
+    const timeSeriesCommand = (query: string) =>
+      client.command({
+        query,
+        clickhouse_settings: { allow_experimental_time_series_table: 1 },
+      });
+
+    const version = (tableName: string) =>
+      new Metadata(hdxClient, new MetadataCache()).getTimeSeriesTableVersion({
+        connectionId: 'test_connection',
+        databaseName: 'default',
+        tableName,
+      });
+
+    beforeAll(async () => {
+      await timeSeriesCommand(
+        `CREATE OR REPLACE TABLE default.${defaultTable} ENGINE = TimeSeries`,
+      );
+      await timeSeriesCommand(
+        `CREATE OR REPLACE TABLE default.${v7Table} ENGINE = TimeSeries SETTINGS version = 7`,
+      );
+    });
+
+    afterAll(async () => {
+      await timeSeriesCommand(`DROP TABLE IF EXISTS default.${defaultTable}`);
+      await timeSeriesCommand(`DROP TABLE IF EXISTS default.${v7Table}`);
+    });
+
+    it('reads the version from the table definition', async () => {
+      expect(await version(defaultTable)).toBe(8);
+      expect(await version(v7Table)).toBe(7);
+    });
+
+    it('answers 0 for a table that does not exist', async () => {
+      expect(await version('test_ts_version_missing')).toBe(0);
+    });
+  });
+
   describe('getTimeSeriesTables', () => {
     const database = 'test_ts_discovery';