@mastra/clickhouse 1.0.0-beta.11 → 1.0.0-beta.12

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @mastra/clickhouse
 
+## 1.0.0-beta.12
+
+### Patch Changes
+
+- Fixed duplicate spans migration issue across all storage backends. When upgrading from older versions, existing duplicate (traceId, spanId) combinations in the spans table could prevent the unique constraint from being created. The migration deduplicates spans before adding the constraint. ([#12073](https://github.com/mastra-ai/mastra/pull/12073))
+
+  **Deduplication rules (in priority order):**
+  1. Keep completed spans (those with `endedAt` set) over incomplete spans
+  2. Among spans with the same completion status, keep the one with the newest `updatedAt`
+  3. Use `createdAt` as the final tiebreaker
+
+  **What changed:**
+  - Added `migrateSpans()` method to observability stores for manual migration
+  - Added `checkSpansMigrationStatus()` method to check if migration is needed
+  - All stores use optimized single-query deduplication to avoid memory issues on large tables
+
+  **Usage example:**
+
+  ```typescript
+  const observability = await storage.getStore('observability');
+  const status = await observability.checkSpansMigrationStatus();
+  if (status.needsMigration) {
+    const result = await observability.migrateSpans();
+    console.log(`Migration complete: ${result.duplicatesRemoved} duplicates removed`);
+  }
+  ```
+
+  Fixes #11840
+
+- Renamed MastraStorage to MastraCompositeStore for better clarity. The old MastraStorage name remains available as a deprecated alias for backward compatibility, but will be removed in a future version. ([#12093](https://github.com/mastra-ai/mastra/pull/12093))
+
+  **Migration:**
+
+  Update your imports and usage:
+
+  ```typescript
+  // Before
+  import { MastraStorage } from '@mastra/core/storage';
+
+  const storage = new MastraStorage({
+    id: 'composite',
+    domains: { ... }
+  });
+
+  // After
+  import { MastraCompositeStore } from '@mastra/core/storage';
+
+  const storage = new MastraCompositeStore({
+    id: 'composite',
+    domains: { ... }
+  });
+  ```
+
+  The new name better reflects that this is a composite storage implementation that routes different domains (workflows, traces, messages) to different underlying stores, avoiding confusion with the general "Mastra Storage" concept.
+
+- Updated dependencies [[`026b848`](https://github.com/mastra-ai/mastra/commit/026b8483fbf5b6d977be8f7e6aac8d15c75558ac), [`ffa553a`](https://github.com/mastra-ai/mastra/commit/ffa553a3edc1bd17d73669fba66d6b6f4ac10897)]:
+  - @mastra/core@1.0.0-beta.26
+
 ## 1.0.0-beta.11
 
 ### Patch Changes

package/dist/docs/README.md

@@ -28,4 +28,4 @@ docs/
 ## Version
 
 Package: @mastra/clickhouse
-Version: 1.0.0-beta.11
+Version: 1.0.0-beta.12

package/dist/docs/SKILL.md

@@ -5,7 +5,7 @@ description: Documentation for @mastra/clickhouse. Includes links to type defini
 
 # @mastra/clickhouse Documentation
 
-> **Version**: 1.0.0-beta.11
+> **Version**: 1.0.0-beta.12
 > **Package**: @mastra/clickhouse
 
 ## Quick Navigation

package/dist/docs/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-beta.11",
+  "version": "1.0.0-beta.12",
   "package": "@mastra/clickhouse",
   "exports": {},
   "modules": {}

package/dist/docs/storage/01-reference.md

@@ -9,11 +9,11 @@
 
 > Documentation for combining multiple storage backends in Mastra.
 
-`MastraStorage` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
+`MastraCompositeStore` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
 
 ## Installation
 
-`MastraStorage` is included in `@mastra/core`:
+`MastraCompositeStore` is included in `@mastra/core`:
 
 ```bash
 npm install @mastra/core@beta
@@ -44,13 +44,13 @@ Mastra organizes storage into five specialized domains, each handling a specific
 Import domain classes directly from each store package and compose them:
 
 ```typescript title="src/mastra/index.ts"
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { MemoryLibSQL } from "@mastra/libsql";
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
-  storage: new MastraStorage({
+  storage: new MastraCompositeStore({
     id: "composite",
     domains: {
       memory: new MemoryLibSQL({ url: "file:./local.db" }),
@@ -66,7 +66,7 @@ export const mastra = new Mastra({
 Use `default` to specify a fallback storage, then override specific domains:
 
 ```typescript title="src/mastra/index.ts"
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { PostgresStore } from "@mastra/pg";
 import { MemoryLibSQL } from "@mastra/libsql";
 import { Mastra } from "@mastra/core";
@@ -77,7 +77,7 @@ const pgStore = new PostgresStore({
 });
 
 export const mastra = new Mastra({
-  storage: new MastraStorage({
+  storage: new MastraCompositeStore({
     id: "composite",
     default: pgStore,
     domains: {
@@ -91,14 +91,14 @@ export const mastra = new Mastra({
 
 ## Initialization
 
-`MastraStorage` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
+`MastraCompositeStore` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
 
 ```typescript title="src/mastra/index.ts"
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { Mastra } from "@mastra/core";
 
-const storage = new MastraStorage({
+const storage = new MastraCompositeStore({
   id: "composite",
   domains: {
     memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
@@ -115,10 +115,10 @@ export const mastra = new Mastra({
 If using storage directly, call `init()` explicitly:
 
 ```typescript
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryPG } from "@mastra/pg";
 
-const storage = new MastraStorage({
+const storage = new MastraCompositeStore({
   id: "composite",
   domains: {
     memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
@@ -139,11 +139,11 @@ const thread = await memoryStore?.getThreadById({ threadId: "..." });
 Use a local database for development while keeping production data in a managed service:
 
 ```typescript
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { MemoryLibSQL } from "@mastra/libsql";
 
-const storage = new MastraStorage({
+const storage = new MastraCompositeStore({
   id: "composite",
   domains: {
     // Use local SQLite for development, PostgreSQL for production
@@ -162,11 +162,11 @@ const storage = new MastraStorage({
 Use a time-series database for traces while keeping other data in PostgreSQL:
 
 ```typescript
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
 
-const storage = new MastraStorage({
+const storage = new MastraCompositeStore({
   id: "composite",
   domains: {
     memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),

package/dist/index.cjs

@@ -15,8 +15,10 @@ var TABLE_ENGINES = {
   [storage.TABLE_THREADS]: `ReplacingMergeTree()`,
   [storage.TABLE_SCORERS]: `MergeTree()`,
   [storage.TABLE_RESOURCES]: `ReplacingMergeTree()`,
-  // TODO: verify this is the correct engine for Spans when implementing clickhouse storage
-  [storage.TABLE_SPANS]: `ReplacingMergeTree()`,
+  // ReplacingMergeTree(updatedAt) deduplicates rows with the same (traceId, spanId) sorting key,
+  // keeping the row with the highest updatedAt value. Combined with ORDER BY (traceId, spanId),
+  // this provides eventual uniqueness for the (traceId, spanId) composite key.
+  [storage.TABLE_SPANS]: `ReplacingMergeTree(updatedAt)`,
   mastra_agents: `ReplacingMergeTree()`
 };
 var COLUMN_TYPES = {
@@ -99,6 +101,213 @@ var ClickhouseDB = class extends base.MastraBase {
     const columns = await result.json();
     return columns.some((c) => c.name === column);
   }
+  /**
+   * Checks if a table exists in the database.
+   */
+  async tableExists(tableName) {
+    try {
+      const result = await this.client.query({
+        query: `EXISTS TABLE ${tableName}`,
+        format: "JSONEachRow"
+      });
+      const rows = await result.json();
+      return rows[0]?.result === 1;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Gets the sorting key (ORDER BY columns) for a table.
+   * Returns null if the table doesn't exist.
+   */
+  async getTableSortingKey(tableName) {
+    try {
+      const result = await this.client.query({
+        query: `SELECT sorting_key FROM system.tables WHERE database = currentDatabase() AND name = {tableName:String}`,
+        query_params: { tableName },
+        format: "JSONEachRow"
+      });
+      const rows = await result.json();
+      return rows[0]?.sorting_key ?? null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Checks if migration is needed for the spans table.
+   * Returns information about the current state.
+   */
+  async checkSpansMigrationStatus(tableName) {
+    const exists = await this.tableExists(tableName);
+    if (!exists) {
+      return { needsMigration: false, currentSortingKey: null };
+    }
+    const currentSortingKey = await this.getTableSortingKey(tableName);
+    if (!currentSortingKey) {
+      return { needsMigration: false, currentSortingKey: null };
+    }
+    const needsMigration = currentSortingKey.toLowerCase().startsWith("createdat");
+    return { needsMigration, currentSortingKey };
+  }
+  /**
+   * Checks for duplicate (traceId, spanId) combinations in the spans table.
+   * Returns information about duplicates for logging/CLI purposes.
+   */
+  async checkForDuplicateSpans(tableName) {
+    try {
+      const result = await this.client.query({
+        query: `
+          SELECT count() as duplicate_count
+          FROM (
+            SELECT traceId, spanId
+            FROM ${tableName}
+            GROUP BY traceId, spanId
+            HAVING count() > 1
+          )
+        `,
+        format: "JSONEachRow"
+      });
+      const rows = await result.json();
+      const duplicateCount = parseInt(rows[0]?.duplicate_count ?? "0", 10);
+      return {
+        hasDuplicates: duplicateCount > 0,
+        duplicateCount
+      };
+    } catch (error) {
+      this.logger?.debug?.(`Could not check for duplicates: ${error}`);
+      return { hasDuplicates: false, duplicateCount: 0 };
+    }
+  }
+  /**
+   * Migrates the spans table from the old sorting key (createdAt, traceId, spanId)
+   * to the new sorting key (traceId, spanId) for proper uniqueness enforcement.
+   *
+   * This migration:
+   * 1. Renames the old table to a backup
+   * 2. Creates a new table with the correct sorting key
+   * 3. Copies all data from the backup to the new table, deduplicating by (traceId, spanId)
+   *    using priority-based selection:
+   *    - First, prefer completed spans (those with endedAt set)
+   *    - Then prefer the most recently updated span (highest updatedAt)
+   *    - Finally use creation time as tiebreaker (highest createdAt)
+   * 4. Drops the backup table
+   *
+   * The deduplication strategy matches the PostgreSQL migration (PR #12073) to ensure
+   * consistent behavior across storage backends.
+   *
+   * The migration is idempotent - it only runs if the old sorting key is detected.
+   *
+   * @returns true if migration was performed, false if not needed
+   */
+  async migrateSpansTableSortingKey({
+    tableName,
+    schema
+  }) {
+    if (tableName !== storage.TABLE_SPANS) {
+      return false;
+    }
+    const exists = await this.tableExists(tableName);
+    if (!exists) {
+      return false;
+    }
+    const currentSortingKey = await this.getTableSortingKey(tableName);
+    if (!currentSortingKey) {
+      return false;
+    }
+    const needsMigration = currentSortingKey.toLowerCase().startsWith("createdat");
+    if (!needsMigration) {
+      this.logger?.debug?.(`Spans table already has correct sorting key: ${currentSortingKey}`);
+      return false;
+    }
+    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;
+    try {
+      await this.client.command({
+        query: `RENAME TABLE ${tableName} TO ${backupTableName}`
+      });
+      const columns = Object.entries(schema).map(([name, def]) => {
+        let sqlType = this.getSqlType(def.type);
+        let isNullable = def.nullable === true;
+        if (tableName === storage.TABLE_SPANS && name === "updatedAt") {
+          isNullable = false;
+        }
+        if (isNullable) {
+          sqlType = `Nullable(${sqlType})`;
+        }
+        const constraints = [];
+        if (name === "metadata" && (def.type === "text" || def.type === "jsonb") && isNullable) {
+          constraints.push("DEFAULT '{}'");
+        }
+        const columnTtl = this.ttl?.[tableName]?.columns?.[name];
+        return `"${name}" ${sqlType} ${constraints.join(" ")} ${columnTtl ? `TTL toDateTime(${columnTtl.ttlKey ?? "createdAt"}) + INTERVAL ${columnTtl.interval} ${columnTtl.unit}` : ""}`;
+      }).join(",\n");
+      const createSql = `
+        CREATE TABLE ${tableName} (
+          ${columns}
+        )
+        ENGINE = ${TABLE_ENGINES[tableName] ?? "MergeTree()"}
+        PRIMARY KEY (traceId, spanId)
+        ORDER BY (traceId, spanId)
+        ${rowTtl ? `TTL toDateTime(${rowTtl.ttlKey ?? "createdAt"}) + INTERVAL ${rowTtl.interval} ${rowTtl.unit}` : ""}
+        SETTINGS index_granularity = 8192
+      `;
+      await this.client.command({
+        query: createSql
+      });
+      const describeResult = await this.client.query({
+        query: `DESCRIBE TABLE ${backupTableName}`,
+        format: "JSONEachRow"
+      });
+      const backupColumns = await describeResult.json();
+      const backupColumnNames = new Set(backupColumns.map((c) => c.name));
+      const columnsToInsert = Object.keys(schema).filter((col) => backupColumnNames.has(col));
+      const columnList = columnsToInsert.map((c) => `"${c}"`).join(", ");
+      const selectExpressions = columnsToInsert.map((c) => c === "updatedAt" ? `COALESCE("updatedAt", "createdAt") as "updatedAt"` : `"${c}"`).join(", ");
+      await this.client.command({
+        query: `INSERT INTO ${tableName} (${columnList})
+                SELECT ${selectExpressions}
+                FROM ${backupTableName}
+                ORDER BY traceId, spanId,
+                         (endedAt IS NOT NULL AND endedAt != '') DESC,
+                         COALESCE(updatedAt, createdAt) DESC,
+                         createdAt DESC
+                LIMIT 1 BY traceId, spanId`
+      });
+      await this.client.command({
+        query: `DROP TABLE ${backupTableName}`
+      });
+      this.logger?.info?.(`Successfully migrated spans table to new sorting key`);
+      return true;
+    } catch (error$1) {
+      this.logger?.error?.(`Migration failed: ${error$1.message}`);
+      try {
+        const originalExists = await this.tableExists(tableName);
+        const backupExists = await this.tableExists(backupTableName);
+        if (!originalExists && backupExists) {
+          this.logger?.info?.(`Restoring spans table from backup`);
+          await this.client.command({
+            query: `RENAME TABLE ${backupTableName} TO ${tableName}`
+          });
+        } else if (originalExists && backupExists) {
+          await this.client.command({
+            query: `DROP TABLE IF EXISTS ${backupTableName}`
+          });
+        }
+      } catch (restoreError) {
+        this.logger?.error?.(`Failed to restore from backup: ${restoreError}`);
+      }
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("CLICKHOUSE", "MIGRATE_SPANS_SORTING_KEY", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: { tableName, currentSortingKey }
+        },
+        error$1
+      );
+    }
+  }
   getSqlType(type) {
     switch (type) {
       case "text":
@@ -125,7 +334,10 @@ var ClickhouseDB = class extends base.MastraBase {
     try {
       const columns = Object.entries(schema).map(([name, def]) => {
         let sqlType = this.getSqlType(def.type);
-        const isNullable = def.nullable === true;
+        let isNullable = def.nullable === true;
+        if (tableName === storage.TABLE_SPANS && name === "updatedAt") {
+          isNullable = false;
+        }
         if (isNullable) {
           sqlType = `Nullable(${sqlType})`;
         }
@@ -155,8 +367,8 @@ var ClickhouseDB = class extends base.MastraBase {
               ${columns}
             )
             ENGINE = ${TABLE_ENGINES[tableName] ?? "MergeTree()"}
-            PRIMARY KEY (createdAt, traceId, spanId)
-            ORDER BY (createdAt, traceId, spanId)
+            PRIMARY KEY (traceId, spanId)
+            ORDER BY (traceId, spanId)
             ${rowTtl ? `TTL toDateTime(${rowTtl.ttlKey ?? "createdAt"}) + INTERVAL ${rowTtl.interval} ${rowTtl.unit}` : ""}
             SETTINGS index_granularity = 8192
           `;
@@ -302,7 +514,9 @@ var ClickhouseDB = class extends base.MastraBase {
       ...Object.fromEntries(
         Object.entries(record).map(([key, value]) => [
           key,
-          storage.TABLE_SCHEMAS[tableName]?.[key]?.type === "timestamp" ? new Date(value).toISOString() : value
+          // Only convert to Date if it's a timestamp column AND value is not null/undefined
+          // new Date(null) returns epoch date, not null, so we must check first
+          storage.TABLE_SCHEMAS[tableName]?.[key]?.type === "timestamp" && value != null ? new Date(value).toISOString() : value
         ])
       )
     }));
@@ -1644,11 +1858,101 @@ var ObservabilityStorageClickhouse = class extends storage.ObservabilityStorage
     this.#db = new ClickhouseDB({ client, ttl });
   }
   async init() {
+    const migrationStatus = await this.#db.checkSpansMigrationStatus(storage.TABLE_SPANS);
+    if (migrationStatus.needsMigration) {
+      const duplicateInfo = await this.#db.checkForDuplicateSpans(storage.TABLE_SPANS);
+      const duplicateMessage = duplicateInfo.hasDuplicates ? `
+Found ${duplicateInfo.duplicateCount} duplicate (traceId, spanId) combinations that will be removed.
+` : "";
+      const errorMessage = `
+===========================================================================
+MIGRATION REQUIRED: ClickHouse spans table needs sorting key update
+===========================================================================
+
+The spans table structure has changed. ClickHouse requires a table recreation
+to update the sorting key from (traceId) to (traceId, spanId).
+` + duplicateMessage + `
+To fix this, run the manual migration command:
+
+  npx mastra migrate
+
+This command will:
+  1. Create a new table with the correct sorting key
+  2. Copy data from the old table (deduplicating if needed)
+  3. Replace the old table with the new one
+
+WARNING: This migration involves table recreation and may take significant
+time for large tables. Please ensure you have a backup before proceeding.
+===========================================================================
+`;
+      throw new error.MastraError({
+        id: storage.createStorageErrorId("CLICKHOUSE", "MIGRATION_REQUIRED", "SORTING_KEY_CHANGE"),
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        text: errorMessage
+      });
+    }
     await this.#db.createTable({ tableName: storage.TABLE_SPANS, schema: storage.SPAN_SCHEMA });
   }
   async dangerouslyClearAll() {
     await this.#db.clearTable({ tableName: storage.TABLE_SPANS });
   }
+  /**
+   * Manually run the spans migration to deduplicate and update the sorting key.
+   * This is intended to be called from the CLI when duplicates are detected.
+   *
+   * @returns Migration result with status and details
+   */
+  async migrateSpans() {
+    const migrationStatus = await this.#db.checkSpansMigrationStatus(storage.TABLE_SPANS);
+    if (!migrationStatus.needsMigration) {
+      return {
+        success: true,
+        alreadyMigrated: true,
+        duplicatesRemoved: 0,
+        message: `Migration already complete. Spans table has correct sorting key.`
+      };
+    }
+    const duplicateInfo = await this.#db.checkForDuplicateSpans(storage.TABLE_SPANS);
+    if (duplicateInfo.hasDuplicates) {
+      this.logger?.info?.(
+        `Found ${duplicateInfo.duplicateCount} duplicate (traceId, spanId) combinations. Starting migration with deduplication...`
+      );
+    } else {
+      this.logger?.info?.(`No duplicate spans found. Starting sorting key migration...`);
+    }
+    await this.#db.migrateSpansTableSortingKey({ tableName: storage.TABLE_SPANS, schema: storage.SPAN_SCHEMA });
+    return {
+      success: true,
+      alreadyMigrated: false,
+      duplicatesRemoved: duplicateInfo.duplicateCount,
+      message: duplicateInfo.hasDuplicates ? `Migration complete. Removed duplicates and updated sorting key for ${storage.TABLE_SPANS}.` : `Migration complete. Updated sorting key for ${storage.TABLE_SPANS}.`
+    };
+  }
+  /**
+   * Check migration status for the spans table.
+   * Returns information about whether migration is needed.
+   */
+  async checkSpansMigrationStatus() {
+    const migrationStatus = await this.#db.checkSpansMigrationStatus(storage.TABLE_SPANS);
+    if (!migrationStatus.needsMigration) {
+      return {
+        needsMigration: false,
+        hasDuplicates: false,
+        duplicateCount: 0,
+        constraintExists: true,
+        tableName: storage.TABLE_SPANS
+      };
+    }
+    const duplicateInfo = await this.#db.checkForDuplicateSpans(storage.TABLE_SPANS);
+    return {
+      needsMigration: true,
+      hasDuplicates: duplicateInfo.hasDuplicates,
+      duplicateCount: duplicateInfo.duplicateCount,
+      constraintExists: false,
+      tableName: storage.TABLE_SPANS
+    };
+  }
   get tracingStrategy() {
     return {
       preferred: "insert-only",
@@ -1982,10 +2286,10 @@ var ObservabilityStorageClickhouse = class extends storage.ObservabilityStorage
               conditions.push(`(error IS NOT NULL AND error != '')`);
               break;
             case storage.TraceStatus.RUNNING:
-              conditions.push(`(endedAt IS NULL OR endedAt = '') AND (error IS NULL OR error = '')`);
+              conditions.push(`endedAt IS NULL AND (error IS NULL OR error = '')`);
               break;
             case storage.TraceStatus.SUCCESS:
-              conditions.push(`(endedAt IS NOT NULL AND endedAt != '') AND (error IS NULL OR error = '')`);
+              conditions.push(`endedAt IS NOT NULL AND (error IS NULL OR error = '')`);
               break;
           }
         }
@@ -2014,7 +2318,7 @@ var ObservabilityStorageClickhouse = class extends storage.ObservabilityStorage
       if (sortField === "endedAt") {
         const nullSortValue = sortDirection === "DESC" ? 0 : 1;
         const nonNullSortValue = sortDirection === "DESC" ? 1 : 0;
-        orderClause = `ORDER BY CASE WHEN ${sortField} IS NULL OR ${sortField} = '' THEN ${nullSortValue} ELSE ${nonNullSortValue} END, ${sortField} ${sortDirection}`;
+        orderClause = `ORDER BY CASE WHEN ${sortField} IS NULL THEN ${nullSortValue} ELSE ${nonNullSortValue} END, ${sortField} ${sortDirection}`;
       } else {
         orderClause = `ORDER BY ${sortField} ${sortDirection}`;
       }
@@ -2920,7 +3224,7 @@ var WorkflowsStorageClickhouse = class extends storage.WorkflowsStorage {
 var isClientConfig = (config) => {
   return "client" in config;
 };
-var ClickhouseStore = class extends storage.MastraStorage {
+var ClickhouseStore = class extends storage.MastraCompositeStore {
   db;
   ttl = {};
   stores;