Skip to content

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.ts
index 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
.clickhouseClustered
diff --git a/apps/api/src/config/env.ts b/apps/api/src/config/env.ts
index 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.ts
index 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}
END
diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
index 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.ts
index 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 image
diff --git a/packages/core/src/modules/cohort/src/cohort-sql.test.ts b/packages/core/src/modules/cohort/src/cohort-sql.test.ts
index 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.ts
index 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.ts
index 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: string
diff --git a/packages/db/src/clickhouse/client.ts b/packages/db/src/clickhouse/client.ts
index 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'
);
}