OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
clickhouse: key clustered mutations on CLICKHOUSE_CLUSTER alone
Carl-Gerhard Lindesvärd9a16fee2e384
diff --git a/apps/api/src/config/env.test.ts b/apps/api/src/config/env.test.tsindex 7343eadf0..8492175a6 100644--- a/apps/api/src/config/env.test.ts+++ b/apps/api/src/config/env.test.ts@@ -202,11 +202,14 @@ describe('derived values, computed once in the transform', () => {).toBe('https://own');});- it('clickhouseClustered is CLICKHOUSE_CLUSTER, else the inverse of SELF_HOSTED', () => {- expect(loadConfig(base).core.clickhouseClustered).toBe(true);+ it('clickhouseClustered is CLICKHOUSE_CLUSTER alone, the rule the migrations use', () => {+ expect(loadConfig(base).core.clickhouseClustered).toBe(false);expect(loadConfig({ ...base, SELF_HOSTED: 'true' }).core.clickhouseClustered).toBe(false);+ expect(+ loadConfig({ ...base, CLICKHOUSE_CLUSTER: '1' }).core.clickhouseClustered+ ).toBe(true);expect(loadConfig({ ...base, SELF_HOSTED: 'true', CLICKHOUSE_CLUSTER: '1' }).core.clickhouseClustereddiff --git a/apps/api/src/config/env.ts b/apps/api/src/config/env.tsindex 328847e2a..8cb847bdc 100644--- a/apps/api/src/config/env.ts+++ b/apps/api/src/config/env.ts@@ -813,8 +813,12 @@ function deriveCoreConfig(raw: RawEnv): CoreConfig {selfHosted: raw.SELF_HOSTED,dashboardUrl: deriveDashboardUrl(raw),demoUserId: raw.DEMO_USER_ID,- // Clustered mode = production (not self-hosted), unless said otherwise.- clickhouseClustered: raw.CLICKHOUSE_CLUSTER || !raw.SELF_HOSTED,+ // The same rule packages/db/scripts/migrate-code.ts applies when it creates+ // the schema: `<table>_replicated ON CLUSTER` exists only when the operator+ // set CLICKHOUSE_CLUSTER. Inferring it from !SELF_HOSTED made any process+ // without that flag (dev, a cloud box that never set it) mutate tables the+ // migrations never created, so cohorts never computed and deletions failed.+ clickhouseClustered: raw.CLICKHOUSE_CLUSTER,encryptionKey: raw.ENCRYPTION_KEY,pingDisabled: raw.DISABLE_PING,logging: {diff --git a/packages/core/src/buffers/profile-backfill-buffer.ts b/packages/core/src/buffers/profile-backfill-buffer.tsindex d51a30263..d4a073580 100644--- a/packages/core/src/buffers/profile-backfill-buffer.ts+++ b/packages/core/src/buffers/profile-backfill-buffer.ts@@ -1,7 +1,7 @@import { sql } from '@openpanel/db/src/clickhouse/sql';import { getRedisCache, type Redis } from '@openpanel/redis';import { getSafeJson } from '@openpanel/shared';-import { getReplicatedTableName, TABLE_NAMES } from '../shared/ch-tables';+import { replicatedTarget, TABLE_NAMES } from '../shared/ch-tables';import { BaseBuffer, type BufferDeps } from './base-buffer';export interface ProfileBackfillEntry {@@ -71,7 +71,10 @@ export class ProfileBackfillBuffer extends BaseBuffer {const entries = Array.from(seen.values());const ch = this.resolveCh();- const table = getReplicatedTableName(+ // `replicatedTarget`, not `sql.id`: the clustered form carries an+ // `ON CLUSTER` clause and is not a bare identifier, so `sql.id` refused it+ // and every backfill flush threw before reaching ClickHouse.+ const target = replicatedTarget(this.deps.config.clickhouseClustered,TABLE_NAMES.events);@@ -97,7 +100,7 @@ export class ProfileBackfillBuffer extends BaseBuffer {);const statement = sql`- UPDATE ${sql.id(table)}+ UPDATE ${target}SET profile_id = CASE session_id${caseClause}ENDdiff --git a/packages/core/src/config.ts b/packages/core/src/config.tsindex 1ce57f3f3..6fb6f0a97 100644--- a/packages/core/src/config.ts+++ b/packages/core/src/config.ts@@ -224,10 +224,7 @@ export interface CoreConfig {dashboardUrl: string;/** Set on the demo deployment only: every session resolves to this user. */demoUserId: string | undefined;- /**- * CLICKHOUSE_CLUSTER, else the inverse of SELF_HOSTED — the one place that- * cross-field rule is applied.- */+ /** CLICKHOUSE_CLUSTER. Must agree with what `migrate:deploy` created. */clickhouseClustered: boolean;/** The single symmetric key for at-rest encryption; 32 bytes as 64 hex. */encryptionKey: string | undefined;diff --git a/packages/core/src/modules/cohort/cohort.service.ts b/packages/core/src/modules/cohort/cohort.service.tsindex 1781e55bd..7fe9ca555 100644--- a/packages/core/src/modules/cohort/cohort.service.ts+++ b/packages/core/src/modules/cohort/cohort.service.ts@@ -36,6 +36,7 @@ import { chQuery } from '../../ch-query';import type { CoreConfig } from '../../config';import type { ServiceDeps, Services } from '../../services';import { formatClickhouseDate } from '../../shared/ch-dates';+import { replicatedTarget } from '../../shared/ch-tables';import type { IServiceProfile } from '../profile/profile.service';import type { IChartEventFilter } from '../report/report.constants';import type {@@ -58,26 +59,6 @@ const TABLE = {eventPropertyProfileSummaryMv: 'event_property_profile_summary_mv',} as const;-/**- * The mutation target for a table: `<name>_replicated ON CLUSTER '{cluster}'`- * when clustered, the plain name otherwise — the exact text- * `getReplicatedTableName` produces (asserted in src/cohort-sql.test.ts).- *- * Built here rather than fed through `sql.id` because the clustered form is- * not an identifier. The `ON CLUSTER` clause is literal template text, and- * `'{cluster}'` is a ClickHouse *macro*, not a `{name:Type}` placeholder — it- * carries no type suffix, so parameter substitution leaves it alone.- */-export function replicatedTarget(- clustered: boolean,- tableName: string-): SqlFragment {- if (clustered) {- return sql`${sql.id(`${tableName}_replicated`)} ON CLUSTER '{cluster}'`;- }- return sql.id(tableName);-}-// Max members materialized into cohort_members per compute. Cohorts larger// than this are silently truncated to an arbitrary subset, so deployments// with bigger cohorts need to raise it — env-tunable to avoid an imagediff --git a/packages/core/src/modules/cohort/src/cohort-sql.test.ts b/packages/core/src/modules/cohort/src/cohort-sql.test.tsindex 467a0c19d..c7412ce6e 100644--- a/packages/core/src/modules/cohort/src/cohort-sql.test.ts+++ b/packages/core/src/modules/cohort/src/cohort-sql.test.ts@@ -28,12 +28,14 @@// so this ports as direct calls instead.import { expect, test } from 'bun:test';-import { getReplicatedTableName } from '../../../shared/ch-tables';+import {+ getReplicatedTableName,+ replicatedTarget,+} from '../../../shared/ch-tables';import type { PropertyBasedCohortDefinition } from '../cohort.constants';import {buildPropertyBasedCohortQuery,deriveCohortQuerySettings,- replicatedTarget,} from '../cohort.service';const PROJECT_ID = 'test-sql-validation';diff --git a/packages/core/src/shared/ch-tables.parity.test.ts b/packages/core/src/shared/ch-tables.parity.test.tsindex dd2fba1a2..b027f7ed6 100644--- a/packages/core/src/shared/ch-tables.parity.test.ts+++ b/packages/core/src/shared/ch-tables.parity.test.ts@@ -17,7 +17,7 @@ describe('ch-tables parity with @openpanel/db', () => {});// The cluster VERDICT is the config loader's since M15-006- // (`config.clickhouseClustered` = CLICKHOUSE_CLUSTER, else not SELF_HOSTED);+ // (`config.clickhouseClustered` = CLICKHOUSE_CLUSTER);// @openpanel/db still reads it itself. Feeding db's verdict in is what makes// this a parity check of the NAME derivation rather than of two env reads.it('derives the same mutation table name for the same verdict', () => {diff --git a/packages/core/src/shared/ch-tables.ts b/packages/core/src/shared/ch-tables.tsindex abc19d8b6..dbfeab353 100644--- a/packages/core/src/shared/ch-tables.ts+++ b/packages/core/src/shared/ch-tables.ts@@ -13,6 +13,8 @@// this map and @openpanel/db's are identical, so a table added on one side// and not the other fails the suite rather than a query.+import { type SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';+export const TABLE_NAMES = {events: 'events',profiles: 'profiles',@@ -51,6 +53,23 @@ export const TABLE_NAMES = {* The verdict is `config.clickhouseClustered`, resolved once by the config* loader from CLICKHOUSE_CLUSTER and SELF_HOSTED.*/+/**+ * The mutation target as a SQL fragment. Built here rather than fed through+ * `sql.id` because the clustered form is not an identifier: the `ON CLUSTER`+ * clause is literal template text, and `'{cluster}'` is a ClickHouse *macro*,+ * not a `{name:Type}` placeholder — it carries no type suffix, so parameter+ * substitution leaves it alone.+ */+export function replicatedTarget(+ clustered: boolean,+ tableName: string+): SqlFragment {+ if (clustered) {+ return sql`${sql.id(`${tableName}_replicated`)} ON CLUSTER '{cluster}'`;+ }+ return sql.id(tableName);+}+export function getReplicatedTableName(clustered: boolean,tableName: stringdiff --git a/packages/db/src/clickhouse/client.ts b/packages/db/src/clickhouse/client.tsindex cb50b86a6..0972ff9be 100644--- a/packages/db/src/clickhouse/client.ts+++ b/packages/db/src/clickhouse/client.ts@@ -80,20 +80,15 @@ export const TABLE_NAMES = {};/**- * Check if ClickHouse is running in clustered mode- * Clustered mode = production (not self-hosted)- * Non-clustered mode = self-hosted environments+ * Whether ClickHouse runs as a cluster with `<table>_replicated` targets.+ * Keyed on CLICKHOUSE_CLUSTER alone — the same rule the code migrations use+ * when they create the schema — so runtime never mutates tables that were+ * never created.*/export function isClickhouseClustered(): boolean {- if (+ return (process.env.CLICKHOUSE_CLUSTER === 'true' ||process.env.CLICKHOUSE_CLUSTER === '1'- ) {- return true;- }-- return !(- process.env.SELF_HOSTED === 'true' || process.env.SELF_HOSTED === '1');}