@mastra/clickhouse 1.9.1 → 1.10.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createClient } from '@clickhouse/client';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { BRANCH_SPAN_TYPES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEDULES, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_FAVORITES, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SKILLS, TABLE_WORKSPACE_VERSIONS, TABLE_WORKSPACES, TABLE_MCP_SERVER_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_CLIENTS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SCORER_DEFINITIONS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_PROMPT_BLOCKS, TABLE_EXPERIMENT_RESULTS, TABLE_EXPERIMENTS, TABLE_DATASET_VERSIONS, TABLE_DATASET_ITEMS, TABLE_DATASETS, TABLE_AGENT_VERSIONS, TABLE_SPANS, TABLE_RESOURCES, TABLE_SCORERS, TABLE_THREADS, TABLE_TRACES, TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, BackgroundTasksStorage, TABLE_SCHEMAS, TABLE_BACKGROUND_TASKS, MemoryStorage, createStorageErrorId, normalizePerPage, calculatePagination, ObservabilityStorage, SPAN_SCHEMA, listTracesArgsSchema, toTraceSpans, ScoresStorage, transformScoreRow, SCORERS_SCHEMA, WorkflowsStorage, MastraCompositeStore, getSqlType, getDefaultValue, safelyParseJSON, listBranchesArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listFeedbackArgsSchema, EntityType, TraceStatus, METRIC_DISTINCT_COLUMNS } from '@mastra/core/storage';
+import { BRANCH_SPAN_TYPES, TABLE_THREAD_STATE, TABLE_HARNESS_SESSIONS, TABLE_NOTIFICATIONS, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEDULES, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_FAVORITES, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SKILLS, TABLE_WORKSPACE_VERSIONS, TABLE_WORKSPACES, TABLE_MCP_SERVER_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_CLIENTS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SCORER_DEFINITIONS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_PROMPT_BLOCKS, TABLE_EXPERIMENT_RESULTS, TABLE_EXPERIMENTS, TABLE_DATASET_VERSIONS, TABLE_DATASET_ITEMS, TABLE_DATASETS, TABLE_AGENT_VERSIONS, TABLE_SPANS, TABLE_RESOURCES, TABLE_SCORERS, TABLE_THREADS, TABLE_TRACES, TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, BackgroundTasksStorage, TABLE_SCHEMAS, TABLE_BACKGROUND_TASKS, MemoryStorage, createStorageErrorId, normalizePerPage, calculatePagination, ObservabilityStorage, SPAN_SCHEMA, listTracesArgsSchema, toTraceSpans, ScoresStorage, transformScoreRow, SCORERS_SCHEMA, WorkflowsStorage, MastraCompositeStore, getSqlType, getDefaultValue, safelyParseJSON, listBranchesArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listFeedbackArgsSchema, EntityType, TraceStatus, METRIC_DISTINCT_COLUMNS } from '@mastra/core/storage';
 import { MastraBase } from '@mastra/core/base';
 import { MessageList } from '@mastra/core/agent';
 import { parseFieldKey } from '@mastra/core/utils';
@@ -8,6 +8,139 @@ import { coreFeatures } from '@mastra/core/features';
 import { saveScorePayloadSchema } from '@mastra/core/evals';
 
 // src/storage/index.ts
+var DEFAULT_ZOOKEEPER_PATH = "/clickhouse/tables/{shard}/{database}/{table}";
+var DEFAULT_REPLICA_NAME = "{replica}";
+var REPLICATED_ENGINE_NAMES = /* @__PURE__ */ new Set(["ReplicatedMergeTree", "ReplicatedReplacingMergeTree"]);
+var SUPPORTED_ENGINE_NAMES = /* @__PURE__ */ new Set(["MergeTree", "ReplacingMergeTree", ...REPLICATED_ENGINE_NAMES]);
+function isReplicationConfigured(replication) {
+  return replication !== void 0;
+}
+function isReplicatedOrSharedEngine(engine) {
+  if (!engine) return false;
+  return engine.startsWith("Replicated") || engine.startsWith("Shared");
+}
+function assertReplicationConfigField(fieldName, value, errorCode) {
+  if (value === void 0) return;
+  if (value.trim() === "") {
+    throw new MastraError({
+      id: createStorageErrorId("CLICKHOUSE", "REPLICATION_CONFIG", errorCode),
+      domain: ErrorDomain.STORAGE,
+      category: ErrorCategory.USER,
+      text: `ClickHouse replication.${fieldName} must be a non-empty string when provided.`
+    });
+  }
+  if (/\s/.test(value) || value.includes("'") || value.includes('"') || value.includes("\\")) {
+    throw new MastraError({
+      id: createStorageErrorId("CLICKHOUSE", "REPLICATION_CONFIG", errorCode),
+      domain: ErrorDomain.STORAGE,
+      category: ErrorCategory.USER,
+      text: `ClickHouse replication.${fieldName} must not contain whitespace or quote characters.`
+    });
+  }
+}
+function validateReplicationConfig(replication) {
+  if (!replication) return;
+  assertReplicationConfigField("cluster", replication.cluster, "INVALID_CLUSTER");
+  assertReplicationConfigField("zookeeperPath", replication.zookeeperPath, "INVALID_ZOOKEEPER_PATH");
+  assertReplicationConfigField("replicaName", replication.replicaName, "INVALID_REPLICA_NAME");
+}
+function quoteClickhouseString(value) {
+  return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+function getEngineNameAndArgs(engine) {
+  const trimmed = engine.trim();
+  const match = trimmed.match(/^(\w+)\s*(?:\((.*)\))?$/s);
+  if (!match) return null;
+  const name = match[1];
+  if (!name) return null;
+  const args = match[2]?.trim() ?? "";
+  if (args && !hasBalancedParens(args)) return null;
+  return { name, args };
+}
+function hasBalancedParens(s) {
+  let depth = 0;
+  for (const c of s) {
+    if (c === "(") depth++;
+    else if (c === ")") {
+      depth--;
+      if (depth < 0) return false;
+    }
+  }
+  return depth === 0;
+}
+function buildReplicatedTableEngine(engine, replication) {
+  if (!replication) return engine;
+  const parsed = getEngineNameAndArgs(engine);
+  if (!parsed || !SUPPORTED_ENGINE_NAMES.has(parsed.name)) return engine;
+  if (isReplicatedOrSharedEngine(parsed.name)) return engine;
+  const zookeeperPath = quoteClickhouseString(replication.zookeeperPath ?? DEFAULT_ZOOKEEPER_PATH);
+  const replicaName = quoteClickhouseString(replication.replicaName ?? DEFAULT_REPLICA_NAME);
+  const replicatedName = parsed.name === "ReplacingMergeTree" ? "ReplicatedReplacingMergeTree" : "ReplicatedMergeTree";
+  const args = [zookeeperPath, replicaName, parsed.args].filter(Boolean).join(", ");
+  return `${replicatedName}(${args})`;
+}
+function addOnClusterToDDL(sql, replication) {
+  const cluster = replication?.cluster?.trim();
+  if (!cluster) return sql;
+  const quotedCluster = quoteClickhouseString(cluster);
+  const onClusterSuffix = ` ON CLUSTER ${quotedCluster}`;
+  const rewrite = (input, pattern) => {
+    return input.replace(pattern, (...args) => {
+      const match = args[0];
+      const source = args[args.length - 1];
+      const offset = args[args.length - 2];
+      const tail = source.slice(offset + match.length);
+      if (/^\s+ON\s+CLUSTER\s/i.test(tail)) return match;
+      return match + onClusterSuffix;
+    });
+  };
+  let out = sql;
+  out = rewrite(out, /\bCREATE\s+TABLE\s+(IF\s+NOT\s+EXISTS\s+)?[^\s(]+/gi);
+  out = rewrite(out, /\bCREATE\s+MATERIALIZED\s+VIEW\s+(IF\s+NOT\s+EXISTS\s+)?[^\s(]+/gi);
+  out = rewrite(out, /\bALTER\s+TABLE\s+[^\s]+/gi);
+  out = rewrite(out, /\bDROP\s+(TABLE|VIEW)\s+(IF\s+EXISTS\s+)?[^\s]+/gi);
+  out = rewrite(out, /\bTRUNCATE\s+TABLE\s+(IF\s+EXISTS\s+)?[^\s]+/gi);
+  out = rewrite(out, /\bOPTIMIZE\s+TABLE\s+[^\s]+/gi);
+  out = rewrite(out, /\bSYSTEM\s+(REFRESH|WAIT)\s+VIEW\s+[^\s;]+/gi);
+  return out;
+}
+function rewriteEngineClauses(sql, replication) {
+  return sql.replace(/ENGINE\s*=\s*(\w+)\s*/gi, (match, engineName, offset, source) => {
+    const argsStart = offset + match.length;
+    if (source[argsStart] !== "(") {
+      return `ENGINE = ${buildReplicatedTableEngine(engineName, replication)}`;
+    }
+    let depth = 0;
+    for (let i = argsStart; i < source.length; i++) {
+      const char = source[i];
+      if (char === "(") depth++;
+      else if (char === ")") {
+        depth--;
+        if (depth === 0) {
+          const engine = `${engineName}${source.slice(argsStart, i + 1)}`;
+          return `ENGINE = ${buildReplicatedTableEngine(engine, replication)}`;
+        }
+      }
+    }
+    return match;
+  });
+}
+function applyReplicationToDDL(sql, replication) {
+  const withReplicatedEngine = replication ? rewriteEngineClauses(sql, replication) : sql;
+  return addOnClusterToDDL(withReplicatedEngine, replication);
+}
+function buildLocalTableReplicationError(tables) {
+  const tableList = tables.map((table) => `  - ${table.name} (${table.engine})`).join("\n");
+  return new MastraError({
+    id: createStorageErrorId("CLICKHOUSE", "REPLICATION", "LOCAL_TABLES_UNSUPPORTED"),
+    domain: ErrorDomain.STORAGE,
+    category: ErrorCategory.USER,
+    text: `ClickHouse replication is enabled, but existing Mastra tables use non-replicated local engines.
+Mastra will not automatically convert existing local tables to replicated tables.
+Please migrate or recreate these tables manually before enabling replication:
+${tableList}`
+  });
+}
 var TABLE_ENGINES = {
   [TABLE_MESSAGES]: `MergeTree()`,
   [TABLE_WORKFLOW_SNAPSHOT]: `ReplacingMergeTree()`,
@@ -44,8 +177,11 @@ var TABLE_ENGINES = {
   mastra_background_tasks: `ReplacingMergeTree()`,
   [TABLE_SCHEDULES]: `ReplacingMergeTree()`,
   [TABLE_SCHEDULE_TRIGGERS]: `MergeTree()`,
+  [TABLE_NOTIFICATIONS]: `ReplacingMergeTree()`,
+  [TABLE_HARNESS_SESSIONS]: `ReplacingMergeTree()`,
   mastra_channel_installations: `ReplacingMergeTree()`,
-  mastra_channel_config: `ReplacingMergeTree()`
+  mastra_channel_config: `ReplacingMergeTree()`,
+  [TABLE_THREAD_STATE]: `ReplacingMergeTree()`
 };
 var COLUMN_TYPES = {
   text: "String",
@@ -93,8 +229,9 @@ function transformRows(rows) {
 
 // src/storage/db/index.ts
 function resolveClickhouseConfig(config) {
+  validateReplicationConfig(config.replication);
   if ("client" in config) {
-    return { client: config.client, ttl: config.ttl };
+    return { client: config.client, ttl: config.ttl, replication: config.replication };
   }
   const client = createClient({
     url: config.url,
@@ -107,18 +244,25 @@ function resolveClickhouseConfig(config) {
       output_format_json_quote_64bit_integers: 0
     }
   });
-  return { client, ttl: config.ttl };
+  return { client, ttl: config.ttl, replication: config.replication };
 }
 var ClickhouseDB = class extends MastraBase {
   ttl;
+  replication;
   client;
   /** Cache of actual table columns: tableName -> Promise<Set<columnName>> (stores in-flight promise to coalesce concurrent calls) */
   tableColumnsCache = /* @__PURE__ */ new Map();
-  constructor({ client, ttl }) {
+  constructor({
+    client,
+    ttl,
+    replication
+  }) {
     super({
       name: "CLICKHOUSE_DB"
     });
+    validateReplicationConfig(replication);
     this.ttl = ttl;
+    this.replication = replication;
     this.client = client;
   }
   /**
@@ -186,6 +330,19 @@ var ClickhouseDB = class extends MastraBase {
       return false;
     }
   }
+  async assertExistingTableCompatibleWithReplication(tableName) {
+    if (!isReplicationConfigured(this.replication)) return;
+    const result = await this.client.query({
+      query: `SELECT name, engine FROM system.tables WHERE database = currentDatabase() AND name = {tableName:String}`,
+      query_params: { tableName },
+      format: "JSONEachRow"
+    });
+    const rows = await result.json();
+    const localTables = rows.filter((row) => row.engine && !isReplicatedOrSharedEngine(row.engine));
+    if (localTables.length > 0) {
+      throw buildLocalTableReplicationError(localTables);
+    }
+  }
   /**
    * Gets the sorting key (ORDER BY columns) for a table.
    * Returns null if the table doesn't exist.
@@ -289,6 +446,14 @@ var ClickhouseDB = class extends MastraBase {
       this.logger?.debug?.(`Spans table already has correct sorting key: ${currentSortingKey}`);
       return false;
     }
+    if (isReplicationConfigured(this.replication)) {
+      throw new MastraError({
+        id: createStorageErrorId("CLICKHOUSE", "REPLICATION", "SPANS_SORTING_KEY_MIGRATION_UNSUPPORTED"),
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        text: "ClickHouse replication is enabled, so Mastra will not run copy-and-swap spans table migrations automatically. Migrate the existing spans table manually before enabling replication."
+      });
+    }
     this.logger?.info?.(`Migrating spans table from sorting key "${currentSortingKey}" to "(traceId, spanId)"`);
     const backupTableName = `${tableName}_backup_${Date.now()}`;
     const rowTtl = this.ttl?.[tableName]?.row;
@@ -339,7 +504,7 @@ var ClickhouseDB = class extends MastraBase {
                 SELECT ${selectExpressions}
                 FROM ${backupTableName}
                 ORDER BY traceId, spanId,
-                         (endedAt IS NOT NULL AND endedAt != '') DESC,
+                         (endedAt IS NOT NULL) DESC,
                          COALESCE(updatedAt, createdAt) DESC,
                          createdAt DESC
                 LIMIT 1 BY traceId, spanId`
@@ -402,6 +567,7 @@ var ClickhouseDB = class extends MastraBase {
     schema
   }) {
     try {
+      await this.assertExistingTableCompatibleWithReplication(tableName);
       const columns = Object.entries(schema).map(([name, def]) => {
         let sqlType = this.getSqlType(def.type);
         let isNullable = def.nullable === true;
@@ -455,7 +621,7 @@ var ClickhouseDB = class extends MastraBase {
           `;
       }
       await this.client.query({
-        query: sql,
+        query: applyReplicationToDDL(sql, this.replication),
         clickhouse_settings: {
           // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
           date_time_input_format: "best_effort",
@@ -500,7 +666,7 @@ var ClickhouseDB = class extends MastraBase {
           const defaultValue = columnDef.nullable === false ? getDefaultValue(columnDef.type) : "";
           const alterSql = `ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS "${columnName}" ${sqlType} ${defaultValue}`.trim();
           await this.client.query({
-            query: alterSql
+            query: addOnClusterToDDL(alterSql, this.replication)
           });
           this.logger?.debug?.(`Added column ${columnName} to table ${tableName}`);
         }
@@ -523,7 +689,7 @@ var ClickhouseDB = class extends MastraBase {
     try {
       await this.client.command({ query: `SYSTEM STOP MERGES ${tableName}` });
       await this.client.command({
-        query: `TRUNCATE TABLE ${tableName}`
+        query: addOnClusterToDDL(`TRUNCATE TABLE ${tableName}`, this.replication)
       });
       await this.client.command({ query: `SYSTEM START MERGES ${tableName}` });
     } catch (error) {
@@ -541,7 +707,7 @@ var ClickhouseDB = class extends MastraBase {
   async dropTable({ tableName }) {
     try {
       await this.client.query({
-        query: `DROP TABLE IF EXISTS ${tableName}`
+        query: addOnClusterToDDL(`DROP TABLE IF EXISTS ${tableName}`, this.replication)
       });
     } catch (error) {
       throw new MastraError(
@@ -735,9 +901,9 @@ var BackgroundTasksStorageClickhouse = class extends BackgroundTasksStorage {
   #db;
   constructor(config) {
     super();
-    const { client, ttl } = resolveClickhouseConfig(config);
+    const { client, ttl, replication } = resolveClickhouseConfig(config);
     this.client = client;
-    this.#db = new ClickhouseDB({ client, ttl });
+    this.#db = new ClickhouseDB({ client, ttl, replication });
   }
   async init() {
     await this.#db.createTable({ tableName: TABLE_BACKGROUND_TASKS, schema: TABLE_SCHEMAS[TABLE_BACKGROUND_TASKS] });
@@ -929,9 +1095,9 @@ var MemoryStorageClickhouse = class extends MemoryStorage {
   #db;
   constructor(config) {
     super();
-    const { client, ttl } = resolveClickhouseConfig(config);
+    const { client, ttl, replication } = resolveClickhouseConfig(config);
     this.client = client;
-    this.#db = new ClickhouseDB({ client, ttl });
+    this.#db = new ClickhouseDB({ client, ttl, replication });
   }
   async init() {
     await this.#db.createTable({ tableName: TABLE_THREADS, schema: TABLE_SCHEMAS[TABLE_THREADS] });
@@ -2192,9 +2358,9 @@ var ObservabilityStorageClickhouse = class extends ObservabilityStorage {
   #db;
   constructor(config) {
     super();
-    const { client, ttl } = resolveClickhouseConfig(config);
+    const { client, ttl, replication } = resolveClickhouseConfig(config);
     this.client = client;
-    this.#db = new ClickhouseDB({ client, ttl });
+    this.#db = new ClickhouseDB({ client, ttl, replication });
   }
   async init() {
     const migrationStatus = await this.#db.checkSpansMigrationStatus(TABLE_SPANS);
@@ -6988,7 +7154,20 @@ async function filterAppliedRetention(client, entries) {
     return current.column !== e.column || current.days !== e.days;
   });
 }
-async function reconcileDiscoveryTables(client) {
+async function assertExistingTablesCompatibleWithReplication(client, replication) {
+  if (!isReplicationConfigured(replication)) return;
+  const result = await client.query({
+    query: `SELECT name, engine FROM system.tables WHERE database = currentDatabase() AND name IN ({tables:Array(String)})`,
+    query_params: { tables: [...ALL_TABLE_NAMES] },
+    format: "JSONEachRow"
+  });
+  const rows = await result.json();
+  const localTable = rows.find((row) => !isReplicatedOrSharedEngine(row.engine));
+  if (localTable) {
+    throw buildLocalTableReplicationError([{ name: localTable.name, engine: localTable.engine }]);
+  }
+}
+async function reconcileDiscoveryTables(client, replication) {
   let engines;
   try {
     const result = await client.query({
@@ -7008,8 +7187,8 @@ async function reconcileDiscoveryTables(client) {
   for (const { table, mv } of targets) {
     const engine = engines.get(table);
     if (!engine || isReplacingMergeTreeEngine(engine)) continue;
-    await client.command({ query: `DROP VIEW IF EXISTS ${mv}` });
-    await client.command({ query: `DROP TABLE IF EXISTS ${table}` });
+    await client.command({ query: addOnClusterToDDL(`DROP VIEW IF EXISTS ${mv}`, replication) });
+    await client.command({ query: addOnClusterToDDL(`DROP TABLE IF EXISTS ${table}`, replication) });
   }
 }
 async function queryNamesByTable(client, query, tables) {
@@ -7088,12 +7267,14 @@ async function detectExistingDeltaCursorStrategy(client) {
 var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
   #client;
   #retention;
+  #replication;
   #deltaCursorStrategyOverride;
   #deltaCursorStrategy = "fallback";
   constructor(config) {
     super();
-    const { client } = resolveClickhouseConfig(config);
+    const { client, replication } = resolveClickhouseConfig(config);
     this.#client = client;
+    this.#replication = replication;
     this.#retention = config.retention;
     this.#deltaCursorStrategyOverride = config.deltaCursorStrategy;
   }
@@ -7114,6 +7295,7 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
       });
     }
     try {
+      await assertExistingTablesCompatibleWithReplication(this.#client, this.#replication);
       const existingStrategy = await detectExistingDeltaCursorStrategy(this.#client);
       if (existingStrategy === "mixed") {
         this.#deltaCursorStrategy = null;
@@ -7127,19 +7309,19 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
       } else {
         this.#deltaCursorStrategy = await detectDeltaCursorStrategy(this.#client, void 0, existingStrategy);
       }
-      await reconcileDiscoveryTables(this.#client);
+      await reconcileDiscoveryTables(this.#client, this.#replication);
       const coreDdl = this.#deltaCursorStrategy === null ? [...BASE_TABLE_DDL, ...BASE_MV_DDL] : [...buildAllTableDDL(), ...buildAllMvDDL(this.#deltaCursorStrategy)];
       for (const ddl of coreDdl) {
-        await this.#client.command({ query: ddl });
+        await this.#client.command({ query: applyReplicationToDDL(ddl, this.#replication) });
       }
       const pendingMigrations = await filterAppliedMigrations(this.#client, ALL_MIGRATIONS);
       for (const migration of pendingMigrations) {
-        await this.#client.command({ query: migration.sql });
+        await this.#client.command({ query: addOnClusterToDDL(migration.sql, this.#replication) });
       }
       if (this.#retention) {
         const pendingRetention = await filterAppliedRetention(this.#client, buildRetentionEntries(this.#retention));
         for (const entry of pendingRetention) {
-          await this.#client.command({ query: entry.sql });
+          await this.#client.command({ query: addOnClusterToDDL(entry.sql, this.#replication) });
         }
       }
       if (this.#deltaCursorStrategy === "serial") {
@@ -7168,12 +7350,20 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
     }
     try {
       for (const ddl of DISCOVERY_MV_DDL) {
-        await this.#client.command({ query: ddl });
+        await this.#client.command({ query: addOnClusterToDDL(ddl, this.#replication) });
       }
-      await this.#client.command({ query: `SYSTEM REFRESH VIEW ${MV_DISCOVERY_VALUES}` });
-      await this.#client.command({ query: `SYSTEM WAIT VIEW ${MV_DISCOVERY_VALUES}` });
-      await this.#client.command({ query: `SYSTEM REFRESH VIEW ${MV_DISCOVERY_PAIRS}` });
-      await this.#client.command({ query: `SYSTEM WAIT VIEW ${MV_DISCOVERY_PAIRS}` });
+      await this.#client.command({
+        query: addOnClusterToDDL(`SYSTEM REFRESH VIEW ${MV_DISCOVERY_VALUES}`, this.#replication)
+      });
+      await this.#client.command({
+        query: addOnClusterToDDL(`SYSTEM WAIT VIEW ${MV_DISCOVERY_VALUES}`, this.#replication)
+      });
+      await this.#client.command({
+        query: addOnClusterToDDL(`SYSTEM REFRESH VIEW ${MV_DISCOVERY_PAIRS}`, this.#replication)
+      });
+      await this.#client.command({
+        query: addOnClusterToDDL(`SYSTEM WAIT VIEW ${MV_DISCOVERY_PAIRS}`, this.#replication)
+      });
     } catch {
     }
   }
@@ -7192,6 +7382,14 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
         message: "Migration already complete. Signal tables already use signal-ID dedupe keys."
       };
     }
+    if (isReplicationConfigured(this.#replication)) {
+      throw new MastraError({
+        id: createStorageErrorId("CLICKHOUSE", "REPLICATION", "SIGNAL_TABLES_MIGRATION_UNSUPPORTED"),
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        text: "ClickHouse replication is enabled, so Mastra will not run copy-and-swap signal table migrations automatically. Migrate existing local signal tables manually before enabling replication."
+      });
+    }
     await migrateSignalTables(this.#client, this.logger);
     return {
       success: true,
@@ -7888,7 +8086,11 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
   async dangerouslyClearAll() {
     try {
       await Promise.all(
-        ALL_TABLE_NAMES.map((table) => this.#client.command({ query: `TRUNCATE TABLE IF EXISTS ${table}` }))
+        ALL_TABLE_NAMES.map(
+          (table) => this.#client.command({
+            query: addOnClusterToDDL(`TRUNCATE TABLE IF EXISTS ${table}`, this.#replication)
+          })
+        )
       );
     } catch (error) {
       if (error instanceof MastraError) throw error;
@@ -7908,9 +8110,9 @@ var ScoresStorageClickhouse = class extends ScoresStorage {
   #db;
   constructor(config) {
     super();
-    const { client, ttl } = resolveClickhouseConfig(config);
+    const { client, ttl, replication } = resolveClickhouseConfig(config);
     this.client = client;
-    this.#db = new ClickhouseDB({ client, ttl });
+    this.#db = new ClickhouseDB({ client, ttl, replication });
   }
   async init() {
     await this.#db.createTable({ tableName: TABLE_SCORERS, schema: TABLE_SCHEMAS[TABLE_SCORERS] });
@@ -8335,9 +8537,9 @@ var WorkflowsStorageClickhouse = class extends WorkflowsStorage {
   #db;
   constructor(config) {
     super();
-    const { client, ttl } = resolveClickhouseConfig(config);
+    const { client, ttl, replication } = resolveClickhouseConfig(config);
     this.client = client;
-    this.#db = new ClickhouseDB({ client, ttl });
+    this.#db = new ClickhouseDB({ client, ttl, replication });
   }
   supportsConcurrentUpdates() {
     return false;
@@ -8629,9 +8831,11 @@ var isClientConfig = (config) => {
 var ClickhouseStore = class extends MastraCompositeStore {
   db;
   ttl = {};
+  replication;
   stores;
   constructor(config) {
     super({ id: config.id, name: "ClickhouseStore", disableInit: config.disableInit });
+    validateReplicationConfig(config.replication);
     if (isClientConfig(config)) {
       this.db = config.client;
     } else {
@@ -8644,7 +8848,7 @@ var ClickhouseStore = class extends MastraCompositeStore {
       if (typeof config.password !== "string") {
         throw new Error("ClickhouseStore: password must be a string.");
       }
-      const { id, ttl, disableInit, clickhouse_settings, ...clientOptions } = config;
+      const { id, ttl, disableInit, replication, clickhouse_settings, ...clientOptions } = config;
       this.db = createClient({
         ...clientOptions,
         clickhouse_settings: {
@@ -8658,7 +8862,8 @@ var ClickhouseStore = class extends MastraCompositeStore {
       });
     }
     this.ttl = config.ttl;
-    const domainConfig = { client: this.db, ttl: this.ttl };
+    this.replication = config.replication;
+    const domainConfig = { client: this.db, ttl: this.ttl, replication: config.replication };
     const workflows = new WorkflowsStorageClickhouse(domainConfig);
     const scores = new ScoresStorageClickhouse(domainConfig);
     const memory = new MemoryStorageClickhouse(domainConfig);
@@ -8674,7 +8879,7 @@ var ClickhouseStore = class extends MastraCompositeStore {
   async optimizeTable({ tableName }) {
     try {
       await this.db.command({
-        query: `OPTIMIZE TABLE ${tableName} FINAL`
+        query: addOnClusterToDDL(`OPTIMIZE TABLE ${tableName} FINAL`, this.replication)
       });
     } catch (error) {
       throw new MastraError(
@@ -8691,7 +8896,7 @@ var ClickhouseStore = class extends MastraCompositeStore {
   async materializeTtl({ tableName }) {
     try {
       await this.db.command({
-        query: `ALTER TABLE ${tableName} MATERIALIZE TTL;`
+        query: addOnClusterToDDL(`ALTER TABLE ${tableName} MATERIALIZE TTL`, this.replication) + ";"
       });
     } catch (error) {
       throw new MastraError(
@@ -8730,7 +8935,7 @@ var ClickhouseStoreVNext = class extends ClickhouseStore {
   constructor(config) {
     super(config);
     this.name = "ClickhouseStoreVNext";
-    const observability = new ObservabilityStorageClickhouseVNext({ client: this.db });
+    const observability = new ObservabilityStorageClickhouseVNext({ client: this.db, replication: config.replication });
     this.stores = {
       ...this.stores,
       observability