@mastra/clickhouse 1.0.0-beta.6 → 1.0.0-beta.7

package/dist/index.js

@@ -1,7 +1,8 @@
 import { createClient } from '@clickhouse/client';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { TABLE_SPANS, TABLE_RESOURCES, TABLE_SCORERS, TABLE_THREADS, TABLE_TRACES, TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, MastraStorage, createStorageErrorId, StoreOperations, TABLE_SCHEMAS, WorkflowsStorage, normalizePerPage, ScoresStorage, transformScoreRow, SCORERS_SCHEMA, calculatePagination, MemoryStorage, safelyParseJSON } from '@mastra/core/storage';
+import { TABLE_SPANS, TABLE_RESOURCES, TABLE_SCORERS, TABLE_THREADS, TABLE_TRACES, TABLE_WORKFLOW_SNAPSHOT, TABLE_MESSAGES, MastraStorage, createStorageErrorId, WorkflowsStorage, TABLE_SCHEMAS, normalizePerPage, ScoresStorage, transformScoreRow, SCORERS_SCHEMA, calculatePagination, MemoryStorage, ObservabilityStorage, SPAN_SCHEMA, listTracesArgsSchema, getSqlType, getDefaultValue, safelyParseJSON, TraceStatus } from '@mastra/core/storage';
 import { MessageList } from '@mastra/core/agent';
+import { MastraBase } from '@mastra/core/base';
 import { saveScorePayloadSchema } from '@mastra/core/evals';
 
 // src/storage/index.ts
@@ -26,6 +27,8 @@ var COLUMN_TYPES = {
   bigint: "Int64",
   boolean: "Bool"
 };
+var JSON_FIELDS = ["content", "attributes", "metadata", "input", "output", "error", "scope", "links"];
+var NULLABLE_STRING_FIELDS = ["parentSpanId", "error"];
 function transformRow(row) {
   if (!row) {
     return row;
@@ -36,8 +39,21 @@ function transformRow(row) {
   if (row.updatedAt) {
     row.updatedAt = new Date(row.updatedAt);
   }
-  if (row.content && typeof row.content === "string") {
-    row.content = safelyParseJSON(row.content);
+  if (row.startedAt) {
+    row.startedAt = new Date(row.startedAt);
+  }
+  if (row.endedAt) {
+    row.endedAt = new Date(row.endedAt);
+  }
+  for (const field of JSON_FIELDS) {
+    if (row[field] && typeof row[field] === "string") {
+      row[field] = safelyParseJSON(row[field]);
+    }
+  }
+  for (const field of NULLABLE_STRING_FIELDS) {
+    if (row[field] === "") {
+      row[field] = null;
+    }
   }
   return row;
 }
@@ -45,6 +61,326 @@ function transformRows(rows) {
   return rows.map((row) => transformRow(row));
 }
 
+// src/storage/db/index.ts
+function resolveClickhouseConfig(config) {
+  if ("client" in config) {
+    return { client: config.client, ttl: config.ttl };
+  }
+  const client = createClient({
+    url: config.url,
+    username: config.username,
+    password: config.password,
+    clickhouse_settings: {
+      date_time_input_format: "best_effort",
+      date_time_output_format: "iso",
+      use_client_time_zone: 1,
+      output_format_json_quote_64bit_integers: 0
+    }
+  });
+  return { client, ttl: config.ttl };
+}
+var ClickhouseDB = class extends MastraBase {
+  ttl;
+  client;
+  constructor({ client, ttl }) {
+    super({
+      name: "CLICKHOUSE_DB"
+    });
+    this.ttl = ttl;
+    this.client = client;
+  }
+  async hasColumn(table, column) {
+    const result = await this.client.query({
+      query: `DESCRIBE TABLE ${table}`,
+      format: "JSONEachRow"
+    });
+    const columns = await result.json();
+    return columns.some((c) => c.name === column);
+  }
+  getSqlType(type) {
+    switch (type) {
+      case "text":
+      case "uuid":
+      case "jsonb":
+        return "String";
+      case "timestamp":
+        return "DateTime64(3)";
+      case "integer":
+      case "bigint":
+        return "Int64";
+      case "float":
+        return "Float64";
+      case "boolean":
+        return "Bool";
+      default:
+        return getSqlType(type);
+    }
+  }
+  async createTable({
+    tableName,
+    schema
+  }) {
+    try {
+      const columns = Object.entries(schema).map(([name, def]) => {
+        let sqlType = this.getSqlType(def.type);
+        const isNullable = def.nullable === true;
+        if (isNullable) {
+          sqlType = `Nullable(${sqlType})`;
+        }
+        const constraints = [];
+        if (name === "metadata" && def.type === "text" && 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 rowTtl = this.ttl?.[tableName]?.row;
+      let sql;
+      if (tableName === TABLE_WORKFLOW_SNAPSHOT) {
+        sql = `
+            CREATE TABLE IF NOT EXISTS ${tableName} (
+              ${["id String"].concat(columns)}
+            )
+            ENGINE = ${TABLE_ENGINES[tableName] ?? "MergeTree()"}
+            PRIMARY KEY (createdAt, run_id, workflow_name)
+            ORDER BY (createdAt, run_id, workflow_name)
+            ${rowTtl ? `TTL toDateTime(${rowTtl.ttlKey ?? "createdAt"}) + INTERVAL ${rowTtl.interval} ${rowTtl.unit}` : ""}
+            SETTINGS index_granularity = 8192
+              `;
+      } else if (tableName === TABLE_SPANS) {
+        sql = `
+            CREATE TABLE IF NOT EXISTS ${tableName} (
+              ${columns}
+            )
+            ENGINE = ${TABLE_ENGINES[tableName] ?? "MergeTree()"}
+            PRIMARY KEY (createdAt, traceId, spanId)
+            ORDER BY (createdAt, traceId, spanId)
+            ${rowTtl ? `TTL toDateTime(${rowTtl.ttlKey ?? "createdAt"}) + INTERVAL ${rowTtl.interval} ${rowTtl.unit}` : ""}
+            SETTINGS index_granularity = 8192
+          `;
+      } else {
+        sql = `
+            CREATE TABLE IF NOT EXISTS ${tableName} (
+              ${columns}
+            )
+            ENGINE = ${TABLE_ENGINES[tableName] ?? "MergeTree()"}
+            PRIMARY KEY (createdAt, ${"id"})
+            ORDER BY (createdAt, ${"id"})
+            ${this.ttl?.[tableName]?.row ? `TTL toDateTime(createdAt) + INTERVAL ${this.ttl[tableName].row.interval} ${this.ttl[tableName].row.unit}` : ""}
+            SETTINGS index_granularity = 8192
+          `;
+      }
+      await this.client.query({
+        query: sql,
+        clickhouse_settings: {
+          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
+          date_time_input_format: "best_effort",
+          date_time_output_format: "iso",
+          use_client_time_zone: 1,
+          output_format_json_quote_64bit_integers: 0
+        }
+      });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "CREATE_TABLE", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { tableName }
+        },
+        error
+      );
+    }
+  }
+  async alterTable({
+    tableName,
+    schema,
+    ifNotExists
+  }) {
+    try {
+      const describeSql = `DESCRIBE TABLE ${tableName}`;
+      const result = await this.client.query({
+        query: describeSql
+      });
+      const rows = await result.json();
+      const existingColumnNames = new Set(rows.data.map((row) => row.name.toLowerCase()));
+      for (const columnName of ifNotExists) {
+        if (!existingColumnNames.has(columnName.toLowerCase()) && schema[columnName]) {
+          const columnDef = schema[columnName];
+          let sqlType = this.getSqlType(columnDef.type);
+          if (columnDef.nullable !== false) {
+            sqlType = `Nullable(${sqlType})`;
+          }
+          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
+          });
+          this.logger?.debug?.(`Added column ${columnName} to table ${tableName}`);
+        }
+      }
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "ALTER_TABLE", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { tableName }
+        },
+        error
+      );
+    }
+  }
+  async clearTable({ tableName }) {
+    try {
+      await this.client.query({
+        query: `TRUNCATE TABLE ${tableName}`,
+        clickhouse_settings: {
+          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
+          date_time_input_format: "best_effort",
+          date_time_output_format: "iso",
+          use_client_time_zone: 1,
+          output_format_json_quote_64bit_integers: 0
+        }
+      });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "CLEAR_TABLE", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { tableName }
+        },
+        error
+      );
+    }
+  }
+  async dropTable({ tableName }) {
+    await this.client.query({
+      query: `DROP TABLE IF EXISTS ${tableName}`
+    });
+  }
+  async insert({ tableName, record }) {
+    const rawCreatedAt = record.createdAt || record.created_at || /* @__PURE__ */ new Date();
+    const rawUpdatedAt = record.updatedAt || /* @__PURE__ */ new Date();
+    const createdAt = rawCreatedAt instanceof Date ? rawCreatedAt.toISOString() : rawCreatedAt;
+    const updatedAt = rawUpdatedAt instanceof Date ? rawUpdatedAt.toISOString() : rawUpdatedAt;
+    try {
+      await this.client.insert({
+        table: tableName,
+        values: [
+          {
+            ...record,
+            createdAt,
+            updatedAt
+          }
+        ],
+        format: "JSONEachRow",
+        clickhouse_settings: {
+          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
+          output_format_json_quote_64bit_integers: 0,
+          date_time_input_format: "best_effort",
+          use_client_time_zone: 1
+        }
+      });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "INSERT", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { tableName }
+        },
+        error
+      );
+    }
+  }
+  async batchInsert({ tableName, records }) {
+    const recordsToBeInserted = records.map((record) => ({
+      ...Object.fromEntries(
+        Object.entries(record).map(([key, value]) => [
+          key,
+          TABLE_SCHEMAS[tableName]?.[key]?.type === "timestamp" ? new Date(value).toISOString() : value
+        ])
+      )
+    }));
+    try {
+      await this.client.insert({
+        table: tableName,
+        values: recordsToBeInserted,
+        format: "JSONEachRow",
+        clickhouse_settings: {
+          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
+          date_time_input_format: "best_effort",
+          use_client_time_zone: 1,
+          output_format_json_quote_64bit_integers: 0
+        }
+      });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "BATCH_INSERT", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { tableName }
+        },
+        error
+      );
+    }
+  }
+  async load({ tableName, keys }) {
+    try {
+      const engine = TABLE_ENGINES[tableName] ?? "MergeTree()";
+      const keyEntries = Object.entries(keys);
+      const conditions = keyEntries.map(
+        ([key]) => `"${key}" = {var_${key}:${this.getSqlType(TABLE_SCHEMAS[tableName]?.[key]?.type ?? "text")}}`
+      ).join(" AND ");
+      const values = keyEntries.reduce((acc, [key, value]) => {
+        return { ...acc, [`var_${key}`]: value };
+      }, {});
+      const hasUpdatedAt = TABLE_SCHEMAS[tableName]?.updatedAt;
+      const selectClause = `SELECT *, toDateTime64(createdAt, 3) as createdAt${hasUpdatedAt ? ", toDateTime64(updatedAt, 3) as updatedAt" : ""}`;
+      const result = await this.client.query({
+        query: `${selectClause} FROM ${tableName} ${engine.startsWith("ReplacingMergeTree") ? "FINAL" : ""} WHERE ${conditions} ORDER BY createdAt DESC LIMIT 1`,
+        query_params: values,
+        clickhouse_settings: {
+          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
+          date_time_input_format: "best_effort",
+          date_time_output_format: "iso",
+          use_client_time_zone: 1,
+          output_format_json_quote_64bit_integers: 0
+        }
+      });
+      if (!result) {
+        return null;
+      }
+      const rows = await result.json();
+      if (tableName === TABLE_WORKFLOW_SNAPSHOT) {
+        const snapshot = rows.data[0];
+        if (!snapshot) {
+          return null;
+        }
+        if (typeof snapshot.snapshot === "string") {
+          snapshot.snapshot = JSON.parse(snapshot.snapshot);
+        }
+        return transformRow(snapshot);
+      }
+      const data = transformRow(rows.data[0]);
+      return data;
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "LOAD", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { tableName }
+        },
+        error
+      );
+    }
+  }
+};
+
 // src/storage/domains/memory/index.ts
 function serializeMetadata(metadata) {
   if (!metadata || Object.keys(metadata).length === 0) {
@@ -66,11 +402,60 @@ function parseMetadata(metadata) {
 }
 var MemoryStorageClickhouse = class extends MemoryStorage {
   client;
-  operations;
-  constructor({ client, operations }) {
+  #db;
+  constructor(config) {
     super();
+    const { client, ttl } = resolveClickhouseConfig(config);
     this.client = client;
-    this.operations = operations;
+    this.#db = new ClickhouseDB({ client, ttl });
+  }
+  async init() {
+    await this.#db.createTable({ tableName: TABLE_THREADS, schema: TABLE_SCHEMAS[TABLE_THREADS] });
+    await this.#db.createTable({ tableName: TABLE_MESSAGES, schema: TABLE_SCHEMAS[TABLE_MESSAGES] });
+    await this.#db.createTable({ tableName: TABLE_RESOURCES, schema: TABLE_SCHEMAS[TABLE_RESOURCES] });
+    await this.#db.alterTable({
+      tableName: TABLE_MESSAGES,
+      schema: TABLE_SCHEMAS[TABLE_MESSAGES],
+      ifNotExists: ["resourceId"]
+    });
+  }
+  async dangerouslyClearAll() {
+    await this.#db.clearTable({ tableName: TABLE_MESSAGES });
+    await this.#db.clearTable({ tableName: TABLE_RESOURCES });
+    await this.#db.clearTable({ tableName: TABLE_THREADS });
+  }
+  async deleteMessages(messageIds) {
+    if (!messageIds || messageIds.length === 0) return;
+    try {
+      const result = await this.client.query({
+        query: `SELECT DISTINCT thread_id FROM ${TABLE_MESSAGES} WHERE id IN {messageIds:Array(String)}`,
+        query_params: { messageIds },
+        format: "JSONEachRow"
+      });
+      const rows = await result.json();
+      const threadIds = rows.map((r) => r.thread_id);
+      await this.client.command({
+        query: `DELETE FROM ${TABLE_MESSAGES} WHERE id IN {messageIds:Array(String)}`,
+        query_params: { messageIds }
+      });
+      if (threadIds.length > 0) {
+        const now = (/* @__PURE__ */ new Date()).toISOString().replace("Z", "");
+        await this.client.command({
+          query: `ALTER TABLE ${TABLE_THREADS} UPDATE updatedAt = {now:DateTime64(3)} WHERE id IN {threadIds:Array(String)}`,
+          query_params: { now, threadIds }
+        });
+      }
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "DELETE_MESSAGES", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { count: messageIds.length }
+        },
+        error
+      );
+    }
   }
   async listMessagesById({ messageIds }) {
     if (messageIds.length === 0) return { messages: [] };
@@ -1195,278 +1580,526 @@ var MemoryStorageClickhouse = class extends MemoryStorage {
     }
   }
 };
-var StoreOperationsClickhouse = class extends StoreOperations {
-  ttl;
+var ObservabilityStorageClickhouse = class extends ObservabilityStorage {
   client;
-  constructor({ client, ttl }) {
+  #db;
+  constructor(config) {
     super();
-    this.ttl = ttl;
+    const { client, ttl } = resolveClickhouseConfig(config);
     this.client = client;
+    this.#db = new ClickhouseDB({ client, ttl });
   }
-  async hasColumn(table, column) {
-    const result = await this.client.query({
-      query: `DESCRIBE TABLE ${table}`,
-      format: "JSONEachRow"
-    });
-    const columns = await result.json();
-    return columns.some((c) => c.name === column);
+  async init() {
+    await this.#db.createTable({ tableName: TABLE_SPANS, schema: SPAN_SCHEMA });
   }
-  getSqlType(type) {
-    switch (type) {
-      case "text":
-      case "uuid":
-      case "jsonb":
-        return "String";
-      case "timestamp":
-        return "DateTime64(3)";
-      case "integer":
-      case "bigint":
-        return "Int64";
-      case "float":
-        return "Float64";
-      case "boolean":
-        return "Bool";
-      default:
-        return super.getSqlType(type);
+  async dangerouslyClearAll() {
+    await this.#db.clearTable({ tableName: TABLE_SPANS });
+  }
+  get tracingStrategy() {
+    return {
+      preferred: "insert-only",
+      supported: ["insert-only"]
+    };
+  }
+  async createSpan(args) {
+    const { span } = args;
+    try {
+      const now = Date.now();
+      const record = {
+        ...span,
+        // Convert Date objects to millisecond timestamps for DateTime64(3)
+        startedAt: span.startedAt instanceof Date ? span.startedAt.getTime() : span.startedAt,
+        endedAt: span.endedAt instanceof Date ? span.endedAt.getTime() : span.endedAt,
+        createdAt: now,
+        updatedAt: now
+      };
+      await this.#db.insert({ tableName: TABLE_SPANS, record });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "CREATE_SPAN", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            spanId: span.spanId,
+            traceId: span.traceId,
+            spanType: span.spanType,
+            spanName: span.name
+          }
+        },
+        error
+      );
     }
   }
-  async createTable({
-    tableName,
-    schema
-  }) {
+  async getSpan(args) {
+    const { traceId, spanId } = args;
     try {
-      const columns = Object.entries(schema).map(([name, def]) => {
-        const constraints = [];
-        if (!def.nullable) constraints.push("NOT NULL");
-        if (name === "metadata" && def.type === "text" && def.nullable) {
-          constraints.push("DEFAULT '{}'");
-        }
-        const columnTtl = this.ttl?.[tableName]?.columns?.[name];
-        return `"${name}" ${this.getSqlType(def.type)} ${constraints.join(" ")} ${columnTtl ? `TTL toDateTime(${columnTtl.ttlKey ?? "createdAt"}) + INTERVAL ${columnTtl.interval} ${columnTtl.unit}` : ""}`;
-      }).join(",\n");
-      const rowTtl = this.ttl?.[tableName]?.row;
-      const sql = tableName === TABLE_WORKFLOW_SNAPSHOT ? `
-            CREATE TABLE IF NOT EXISTS ${tableName} (
-              ${["id String"].concat(columns)}
-            )
-            ENGINE = ${TABLE_ENGINES[tableName] ?? "MergeTree()"}
-            PRIMARY KEY (createdAt, run_id, workflow_name)
-            ORDER BY (createdAt, run_id, workflow_name)
-            ${rowTtl ? `TTL toDateTime(${rowTtl.ttlKey ?? "createdAt"}) + INTERVAL ${rowTtl.interval} ${rowTtl.unit}` : ""}
-            SETTINGS index_granularity = 8192
-              ` : `
-            CREATE TABLE IF NOT EXISTS ${tableName} (
-              ${columns}
-            )
-            ENGINE = ${TABLE_ENGINES[tableName] ?? "MergeTree()"}
-            PRIMARY KEY (createdAt, ${"id"})
-            ORDER BY (createdAt, ${"id"})
-            ${this.ttl?.[tableName]?.row ? `TTL toDateTime(createdAt) + INTERVAL ${this.ttl[tableName].row.interval} ${this.ttl[tableName].row.unit}` : ""}
-            SETTINGS index_granularity = 8192
-          `;
-      await this.client.query({
-        query: sql,
+      const engine = TABLE_ENGINES[TABLE_SPANS] ?? "MergeTree()";
+      const result = await this.client.query({
+        query: `
+          SELECT *
+          FROM ${TABLE_SPANS} ${engine.startsWith("ReplacingMergeTree") ? "FINAL" : ""}
+          WHERE traceId = {traceId:String} AND spanId = {spanId:String}
+          LIMIT 1
+        `,
+        query_params: { traceId, spanId },
+        format: "JSONEachRow",
         clickhouse_settings: {
-          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
           date_time_input_format: "best_effort",
           date_time_output_format: "iso",
           use_client_time_zone: 1,
           output_format_json_quote_64bit_integers: 0
         }
       });
+      const rows = await result.json();
+      if (!rows || rows.length === 0) {
+        return null;
+      }
+      const spans = transformRows(rows);
+      const span = spans[0];
+      if (!span) {
+        return null;
+      }
+      return { span };
     } catch (error) {
       throw new MastraError(
         {
-          id: createStorageErrorId("CLICKHOUSE", "CREATE_TABLE", "FAILED"),
+          id: createStorageErrorId("CLICKHOUSE", "GET_SPAN", "FAILED"),
           domain: ErrorDomain.STORAGE,
           category: ErrorCategory.THIRD_PARTY,
-          details: { tableName }
+          details: { traceId, spanId }
         },
         error
       );
     }
   }
-  async alterTable({
-    tableName,
-    schema,
-    ifNotExists
-  }) {
+  async getRootSpan(args) {
+    const { traceId } = args;
     try {
-      const describeSql = `DESCRIBE TABLE ${tableName}`;
+      const engine = TABLE_ENGINES[TABLE_SPANS] ?? "MergeTree()";
       const result = await this.client.query({
-        query: describeSql
+        query: `
+          SELECT *
+          FROM ${TABLE_SPANS} ${engine.startsWith("ReplacingMergeTree") ? "FINAL" : ""}
+          WHERE traceId = {traceId:String} AND (parentSpanId IS NULL OR parentSpanId = '')
+          LIMIT 1
+        `,
+        query_params: { traceId },
+        format: "JSONEachRow",
+        clickhouse_settings: {
+          date_time_input_format: "best_effort",
+          date_time_output_format: "iso",
+          use_client_time_zone: 1,
+          output_format_json_quote_64bit_integers: 0
+        }
       });
       const rows = await result.json();
-      const existingColumnNames = new Set(rows.data.map((row) => row.name.toLowerCase()));
-      for (const columnName of ifNotExists) {
-        if (!existingColumnNames.has(columnName.toLowerCase()) && schema[columnName]) {
-          const columnDef = schema[columnName];
-          let sqlType = this.getSqlType(columnDef.type);
-          if (columnDef.nullable !== false) {
-            sqlType = `Nullable(${sqlType})`;
-          }
-          const defaultValue = columnDef.nullable === false ? this.getDefaultValue(columnDef.type) : "";
-          const alterSql = `ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS "${columnName}" ${sqlType} ${defaultValue}`.trim();
-          await this.client.query({
-            query: alterSql
-          });
-          this.logger?.debug?.(`Added column ${columnName} to table ${tableName}`);
-        }
+      if (!rows || rows.length === 0) {
+        return null;
+      }
+      const spans = transformRows(rows);
+      const span = spans[0];
+      if (!span) {
+        return null;
       }
+      return { span };
     } catch (error) {
       throw new MastraError(
         {
-          id: createStorageErrorId("CLICKHOUSE", "ALTER_TABLE", "FAILED"),
+          id: createStorageErrorId("CLICKHOUSE", "GET_ROOT_SPAN", "FAILED"),
           domain: ErrorDomain.STORAGE,
           category: ErrorCategory.THIRD_PARTY,
-          details: { tableName }
+          details: { traceId }
         },
         error
       );
     }
   }
-  async clearTable({ tableName }) {
+  async getTrace(args) {
+    const { traceId } = args;
     try {
-      await this.client.query({
-        query: `TRUNCATE TABLE ${tableName}`,
+      const engine = TABLE_ENGINES[TABLE_SPANS] ?? "MergeTree()";
+      const result = await this.client.query({
+        query: `
+          SELECT *
+          FROM ${TABLE_SPANS} ${engine.startsWith("ReplacingMergeTree") ? "FINAL" : ""}
+          WHERE traceId = {traceId:String}
+          ORDER BY startedAt DESC
+        `,
+        query_params: { traceId },
+        format: "JSONEachRow",
         clickhouse_settings: {
-          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
           date_time_input_format: "best_effort",
           date_time_output_format: "iso",
           use_client_time_zone: 1,
           output_format_json_quote_64bit_integers: 0
         }
       });
+      const rows = await result.json();
+      if (!rows || rows.length === 0) {
+        return null;
+      }
+      return {
+        traceId,
+        spans: transformRows(rows)
+      };
     } catch (error) {
       throw new MastraError(
         {
-          id: createStorageErrorId("CLICKHOUSE", "CLEAR_TABLE", "FAILED"),
+          id: createStorageErrorId("CLICKHOUSE", "GET_TRACE", "FAILED"),
           domain: ErrorDomain.STORAGE,
           category: ErrorCategory.THIRD_PARTY,
-          details: { tableName }
+          details: { traceId }
+        },
+        error
+      );
+    }
+  }
+  async updateSpan(args) {
+    const { traceId, spanId, updates } = args;
+    try {
+      const existing = await this.#db.load({
+        tableName: TABLE_SPANS,
+        keys: { spanId, traceId }
+      });
+      if (!existing) {
+        throw new MastraError({
+          id: createStorageErrorId("CLICKHOUSE", "UPDATE_SPAN", "NOT_FOUND"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { spanId, traceId }
+        });
+      }
+      const data = { ...updates };
+      if (data.endedAt instanceof Date) {
+        data.endedAt = data.endedAt.getTime();
+      }
+      if (data.startedAt instanceof Date) {
+        data.startedAt = data.startedAt.getTime();
+      }
+      const updated = {
+        ...existing,
+        ...data,
+        updatedAt: Date.now()
+      };
+      await this.client.insert({
+        table: TABLE_SPANS,
+        values: [updated],
+        format: "JSONEachRow",
+        clickhouse_settings: {
+          date_time_input_format: "best_effort",
+          use_client_time_zone: 1,
+          output_format_json_quote_64bit_integers: 0
+        }
+      });
+    } catch (error) {
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "UPDATE_SPAN", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { spanId, traceId }
+        },
+        error
+      );
+    }
+  }
+  async listTraces(args) {
+    const { filters, pagination, orderBy } = listTracesArgsSchema.parse(args);
+    const { page, perPage } = pagination;
+    try {
+      const conditions = [`(parentSpanId IS NULL OR parentSpanId = '')`];
+      const values = {};
+      let paramIndex = 0;
+      if (filters) {
+        if (filters.startedAt?.start) {
+          conditions.push(`startedAt >= {startedAtStart:DateTime64(3)}`);
+          values.startedAtStart = filters.startedAt.start.getTime();
+        }
+        if (filters.startedAt?.end) {
+          conditions.push(`startedAt <= {startedAtEnd:DateTime64(3)}`);
+          values.startedAtEnd = filters.startedAt.end.getTime();
+        }
+        if (filters.endedAt?.start) {
+          conditions.push(`endedAt >= {endedAtStart:DateTime64(3)}`);
+          values.endedAtStart = filters.endedAt.start.getTime();
+        }
+        if (filters.endedAt?.end) {
+          conditions.push(`endedAt <= {endedAtEnd:DateTime64(3)}`);
+          values.endedAtEnd = filters.endedAt.end.getTime();
+        }
+        if (filters.spanType !== void 0) {
+          conditions.push(`spanType = {spanType:String}`);
+          values.spanType = filters.spanType;
+        }
+        if (filters.entityType !== void 0) {
+          conditions.push(`entityType = {entityType:String}`);
+          values.entityType = filters.entityType;
+        }
+        if (filters.entityId !== void 0) {
+          conditions.push(`entityId = {entityId:String}`);
+          values.entityId = filters.entityId;
+        }
+        if (filters.entityName !== void 0) {
+          conditions.push(`entityName = {entityName:String}`);
+          values.entityName = filters.entityName;
+        }
+        if (filters.userId !== void 0) {
+          conditions.push(`userId = {userId:String}`);
+          values.userId = filters.userId;
+        }
+        if (filters.organizationId !== void 0) {
+          conditions.push(`organizationId = {organizationId:String}`);
+          values.organizationId = filters.organizationId;
+        }
+        if (filters.resourceId !== void 0) {
+          conditions.push(`resourceId = {resourceId:String}`);
+          values.resourceId = filters.resourceId;
+        }
+        if (filters.runId !== void 0) {
+          conditions.push(`runId = {runId:String}`);
+          values.runId = filters.runId;
+        }
+        if (filters.sessionId !== void 0) {
+          conditions.push(`sessionId = {sessionId:String}`);
+          values.sessionId = filters.sessionId;
+        }
+        if (filters.threadId !== void 0) {
+          conditions.push(`threadId = {threadId:String}`);
+          values.threadId = filters.threadId;
+        }
+        if (filters.requestId !== void 0) {
+          conditions.push(`requestId = {requestId:String}`);
+          values.requestId = filters.requestId;
+        }
+        if (filters.environment !== void 0) {
+          conditions.push(`environment = {environment:String}`);
+          values.environment = filters.environment;
+        }
+        if (filters.source !== void 0) {
+          conditions.push(`source = {source:String}`);
+          values.source = filters.source;
+        }
+        if (filters.serviceName !== void 0) {
+          conditions.push(`serviceName = {serviceName:String}`);
+          values.serviceName = filters.serviceName;
+        }
+        if (filters.scope != null) {
+          for (const [key, value] of Object.entries(filters.scope)) {
+            if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
+              throw new MastraError({
+                id: createStorageErrorId("CLICKHOUSE", "LIST_TRACES", "INVALID_FILTER_KEY"),
+                domain: ErrorDomain.STORAGE,
+                category: ErrorCategory.USER,
+                details: { key }
+              });
+            }
+            const paramName = `scope_${key}_${paramIndex++}`;
+            conditions.push(`JSONExtractString(scope, '${key}') = {${paramName}:String}`);
+            values[paramName] = typeof value === "string" ? value : JSON.stringify(value);
+          }
+        }
+        if (filters.metadata != null) {
+          for (const [key, value] of Object.entries(filters.metadata)) {
+            if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
+              throw new MastraError({
+                id: createStorageErrorId("CLICKHOUSE", "LIST_TRACES", "INVALID_FILTER_KEY"),
+                domain: ErrorDomain.STORAGE,
+                category: ErrorCategory.USER,
+                details: { key }
+              });
+            }
+            const paramName = `metadata_${key}_${paramIndex++}`;
+            conditions.push(`JSONExtractString(metadata, '${key}') = {${paramName}:String}`);
+            values[paramName] = typeof value === "string" ? value : JSON.stringify(value);
+          }
+        }
+        if (filters.tags != null && filters.tags.length > 0) {
+          for (const tag of filters.tags) {
+            const paramName = `tag_${paramIndex++}`;
+            conditions.push(`has(JSONExtract(tags, 'Array(String)'), {${paramName}:String})`);
+            values[paramName] = tag;
+          }
+        }
+        if (filters.status !== void 0) {
+          switch (filters.status) {
+            case TraceStatus.ERROR:
+              conditions.push(`(error IS NOT NULL AND error != '')`);
+              break;
+            case TraceStatus.RUNNING:
+              conditions.push(`(endedAt IS NULL OR endedAt = '') AND (error IS NULL OR error = '')`);
+              break;
+            case TraceStatus.SUCCESS:
+              conditions.push(`(endedAt IS NOT NULL AND endedAt != '') AND (error IS NULL OR error = '')`);
+              break;
+          }
+        }
+        if (filters.hasChildError !== void 0) {
+          const engine2 = TABLE_ENGINES[TABLE_SPANS] ?? "MergeTree()";
+          const finalClause2 = engine2.startsWith("ReplacingMergeTree") ? "FINAL" : "";
+          if (filters.hasChildError) {
+            conditions.push(`EXISTS (
+              SELECT 1 FROM ${TABLE_SPANS} ${finalClause2} c
+              WHERE c.traceId = ${TABLE_SPANS}.traceId AND c.error IS NOT NULL AND c.error != ''
+            )`);
+          } else {
+            conditions.push(`NOT EXISTS (
+              SELECT 1 FROM ${TABLE_SPANS} ${finalClause2} c
+              WHERE c.traceId = ${TABLE_SPANS}.traceId AND c.error IS NOT NULL AND c.error != ''
+            )`);
+          }
+        }
+      }
+      const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+      const engine = TABLE_ENGINES[TABLE_SPANS] ?? "MergeTree()";
+      const finalClause = engine.startsWith("ReplacingMergeTree") ? "FINAL" : "";
+      const sortField = orderBy.field;
+      const sortDirection = orderBy.direction;
+      let orderClause;
+      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}`;
+      } else {
+        orderClause = `ORDER BY ${sortField} ${sortDirection}`;
+      }
+      const countResult = await this.client.query({
+        query: `SELECT COUNT(*) as count FROM ${TABLE_SPANS} ${finalClause} ${whereClause}`,
+        query_params: values,
+        format: "JSONEachRow"
+      });
+      const countRows = await countResult.json();
+      const total = Number(countRows[0]?.count ?? 0);
+      if (total === 0) {
+        return {
+          pagination: { total: 0, page, perPage, hasMore: false },
+          spans: []
+        };
+      }
+      const result = await this.client.query({
+        query: `
+          SELECT *
+          FROM ${TABLE_SPANS} ${finalClause}
+          ${whereClause}
+          ${orderClause}
+          LIMIT {limit:UInt32}
+          OFFSET {offset:UInt32}
+        `,
+        query_params: { ...values, limit: perPage, offset: page * perPage },
+        format: "JSONEachRow",
+        clickhouse_settings: {
+          date_time_input_format: "best_effort",
+          date_time_output_format: "iso",
+          use_client_time_zone: 1,
+          output_format_json_quote_64bit_integers: 0
+        }
+      });
+      const rows = await result.json();
+      const spans = transformRows(rows);
+      return {
+        pagination: {
+          total,
+          page,
+          perPage,
+          hasMore: (page + 1) * perPage < total
+        },
+        spans
+      };
+    } catch (error) {
+      if (error instanceof MastraError) throw error;
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "LIST_TRACES", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER
         },
         error
       );
     }
   }
-  async dropTable({ tableName }) {
-    await this.client.query({
-      query: `DROP TABLE IF EXISTS ${tableName}`
-    });
-  }
-  async insert({ tableName, record }) {
-    const createdAt = (record.createdAt || record.created_at || /* @__PURE__ */ new Date()).toISOString();
-    const updatedAt = (record.updatedAt || /* @__PURE__ */ new Date()).toISOString();
+  async batchCreateSpans(args) {
     try {
-      const result = await this.client.insert({
-        table: tableName,
-        values: [
-          {
-            ...record,
-            createdAt,
-            updatedAt
-          }
-        ],
-        format: "JSONEachRow",
-        clickhouse_settings: {
-          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
-          output_format_json_quote_64bit_integers: 0,
-          date_time_input_format: "best_effort",
-          use_client_time_zone: 1
-        }
+      const now = Date.now();
+      await this.#db.batchInsert({
+        tableName: TABLE_SPANS,
+        records: args.records.map((record) => ({
+          ...record,
+          // Convert Date objects to millisecond timestamps for DateTime64(3)
+          startedAt: record.startedAt instanceof Date ? record.startedAt.getTime() : record.startedAt,
+          endedAt: record.endedAt instanceof Date ? record.endedAt.getTime() : record.endedAt,
+          createdAt: now,
+          updatedAt: now
+        }))
       });
-      console.info("INSERT RESULT", result);
     } catch (error) {
       throw new MastraError(
         {
-          id: createStorageErrorId("CLICKHOUSE", "INSERT", "FAILED"),
+          id: createStorageErrorId("CLICKHOUSE", "BATCH_CREATE_SPANS", "FAILED"),
           domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { tableName }
+          category: ErrorCategory.THIRD_PARTY
         },
         error
       );
     }
   }
-  async batchInsert({ tableName, records }) {
-    const recordsToBeInserted = records.map((record) => ({
-      ...Object.fromEntries(
-        Object.entries(record).map(([key, value]) => [
-          key,
-          TABLE_SCHEMAS[tableName]?.[key]?.type === "timestamp" ? new Date(value).toISOString() : value
-        ])
-      )
-    }));
+  async batchUpdateSpans(args) {
     try {
-      await this.client.insert({
-        table: tableName,
-        values: recordsToBeInserted,
-        format: "JSONEachRow",
-        clickhouse_settings: {
-          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
-          date_time_input_format: "best_effort",
-          use_client_time_zone: 1,
-          output_format_json_quote_64bit_integers: 0
+      const now = Date.now();
+      for (const record of args.records) {
+        const existing = await this.#db.load({
+          tableName: TABLE_SPANS,
+          keys: { spanId: record.spanId, traceId: record.traceId }
+        });
+        if (existing) {
+          const updates = { ...record.updates };
+          if (updates.startedAt instanceof Date) {
+            updates.startedAt = updates.startedAt.getTime();
+          }
+          if (updates.endedAt instanceof Date) {
+            updates.endedAt = updates.endedAt.getTime();
+          }
+          const updated = {
+            ...existing,
+            ...updates,
+            updatedAt: now
+          };
+          await this.client.insert({
+            table: TABLE_SPANS,
+            values: [updated],
+            format: "JSONEachRow",
+            clickhouse_settings: {
+              date_time_input_format: "best_effort",
+              use_client_time_zone: 1,
+              output_format_json_quote_64bit_integers: 0
+            }
+          });
         }
-      });
+      }
     } catch (error) {
       throw new MastraError(
         {
-          id: createStorageErrorId("CLICKHOUSE", "BATCH_INSERT", "FAILED"),
+          id: createStorageErrorId("CLICKHOUSE", "BATCH_UPDATE_SPANS", "FAILED"),
           domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { tableName }
+          category: ErrorCategory.THIRD_PARTY
         },
         error
       );
     }
   }
-  async load({ tableName, keys }) {
+  async batchDeleteTraces(args) {
     try {
-      const engine = TABLE_ENGINES[tableName] ?? "MergeTree()";
-      const keyEntries = Object.entries(keys);
-      const conditions = keyEntries.map(
-        ([key]) => `"${key}" = {var_${key}:${this.getSqlType(TABLE_SCHEMAS[tableName]?.[key]?.type ?? "text")}}`
-      ).join(" AND ");
-      const values = keyEntries.reduce((acc, [key, value]) => {
-        return { ...acc, [`var_${key}`]: value };
-      }, {});
-      const hasUpdatedAt = TABLE_SCHEMAS[tableName]?.updatedAt;
-      const selectClause = `SELECT *, toDateTime64(createdAt, 3) as createdAt${hasUpdatedAt ? ", toDateTime64(updatedAt, 3) as updatedAt" : ""}`;
-      const result = await this.client.query({
-        query: `${selectClause} FROM ${tableName} ${engine.startsWith("ReplacingMergeTree") ? "FINAL" : ""} WHERE ${conditions} ORDER BY createdAt DESC LIMIT 1`,
-        query_params: values,
-        clickhouse_settings: {
-          // Allows to insert serialized JS Dates (such as '2023-12-06T10:54:48.000Z')
-          date_time_input_format: "best_effort",
-          date_time_output_format: "iso",
-          use_client_time_zone: 1,
-          output_format_json_quote_64bit_integers: 0
-        }
+      if (args.traceIds.length === 0) return;
+      await this.client.command({
+        query: `DELETE FROM ${TABLE_SPANS} WHERE traceId IN {traceIds:Array(String)}`,
+        query_params: { traceIds: args.traceIds }
       });
-      if (!result) {
-        return null;
-      }
-      const rows = await result.json();
-      if (tableName === TABLE_WORKFLOW_SNAPSHOT) {
-        const snapshot = rows.data[0];
-        if (!snapshot) {
-          return null;
-        }
-        if (typeof snapshot.snapshot === "string") {
-          snapshot.snapshot = JSON.parse(snapshot.snapshot);
-        }
-        return transformRow(snapshot);
-      }
-      const data = transformRow(rows.data[0]);
-      return data;
     } catch (error) {
       throw new MastraError(
         {
-          id: createStorageErrorId("CLICKHOUSE", "LOAD", "FAILED"),
+          id: createStorageErrorId("CLICKHOUSE", "BATCH_DELETE_TRACES", "FAILED"),
           domain: ErrorDomain.STORAGE,
-          category: ErrorCategory.THIRD_PARTY,
-          details: { tableName }
+          category: ErrorCategory.THIRD_PARTY
         },
         error
       );
@@ -1475,11 +2108,18 @@ var StoreOperationsClickhouse = class extends StoreOperations {
 };
 var ScoresStorageClickhouse = class extends ScoresStorage {
   client;
-  operations;
-  constructor({ client, operations }) {
+  #db;
+  constructor(config) {
     super();
+    const { client, ttl } = resolveClickhouseConfig(config);
     this.client = client;
-    this.operations = operations;
+    this.#db = new ClickhouseDB({ client, ttl });
+  }
+  async init() {
+    await this.#db.createTable({ tableName: TABLE_SCORERS, schema: TABLE_SCHEMAS[TABLE_SCORERS] });
+  }
+  async dangerouslyClearAll() {
+    await this.#db.clearTable({ tableName: TABLE_SCORERS });
   }
   /**
    * ClickHouse-specific score row transformation.
@@ -1533,7 +2173,7 @@ var ScoresStorageClickhouse = class extends ScoresStorage {
           domain: ErrorDomain.STORAGE,
           category: ErrorCategory.USER,
           details: {
-            scorer: score.scorer?.id ?? "unknown",
+            scorer: typeof score.scorer?.id === "string" ? score.scorer.id : String(score.scorer?.id ?? "unknown"),
             entityId: score.entityId ?? "unknown",
             entityType: score.entityType ?? "unknown",
             traceId: score.traceId ?? "",
@@ -1895,46 +2535,85 @@ var ScoresStorageClickhouse = class extends ScoresStorage {
 };
 var WorkflowsStorageClickhouse = class extends WorkflowsStorage {
   client;
-  operations;
-  constructor({ client, operations }) {
+  #db;
+  constructor(config) {
     super();
-    this.operations = operations;
+    const { client, ttl } = resolveClickhouseConfig(config);
     this.client = client;
+    this.#db = new ClickhouseDB({ client, ttl });
+  }
+  async init() {
+    const schema = TABLE_SCHEMAS[TABLE_WORKFLOW_SNAPSHOT];
+    await this.#db.createTable({ tableName: TABLE_WORKFLOW_SNAPSHOT, schema });
+    await this.#db.alterTable({
+      tableName: TABLE_WORKFLOW_SNAPSHOT,
+      schema,
+      ifNotExists: ["resourceId"]
+    });
+  }
+  async dangerouslyClearAll() {
+    await this.#db.clearTable({ tableName: TABLE_WORKFLOW_SNAPSHOT });
   }
-  updateWorkflowResults({
-    // workflowName,
-    // runId,
-    // stepId,
-    // result,
-    // requestContext,
+  async updateWorkflowResults({
+    workflowName,
+    runId,
+    stepId,
+    result,
+    requestContext
   }) {
-    throw new MastraError({
-      id: createStorageErrorId("CLICKHOUSE", "UPDATE_WORKFLOW_RESULTS", "NOT_IMPLEMENTED"),
-      domain: ErrorDomain.STORAGE,
-      category: ErrorCategory.SYSTEM,
-      text: "Method not implemented."
-    });
+    let snapshot = await this.loadWorkflowSnapshot({ workflowName, runId });
+    if (!snapshot) {
+      snapshot = {
+        context: {},
+        activePaths: [],
+        timestamp: Date.now(),
+        suspendedPaths: {},
+        activeStepsPath: {},
+        resumeLabels: {},
+        serializedStepGraph: [],
+        status: "pending",
+        value: {},
+        waitingPaths: {},
+        runId,
+        requestContext: {}
+      };
+    }
+    snapshot.context[stepId] = result;
+    snapshot.requestContext = { ...snapshot.requestContext, ...requestContext };
+    await this.persistWorkflowSnapshot({ workflowName, runId, snapshot });
+    return snapshot.context;
   }
-  updateWorkflowState({
-    // workflowName,
-    // runId,
-    // opts,
+  async updateWorkflowState({
+    workflowName,
+    runId,
+    opts
   }) {
-    throw new MastraError({
-      id: createStorageErrorId("CLICKHOUSE", "UPDATE_WORKFLOW_STATE", "NOT_IMPLEMENTED"),
-      domain: ErrorDomain.STORAGE,
-      category: ErrorCategory.SYSTEM,
-      text: "Method not implemented."
-    });
+    const snapshot = await this.loadWorkflowSnapshot({ workflowName, runId });
+    if (!snapshot) {
+      return void 0;
+    }
+    if (!snapshot.context) {
+      throw new MastraError({
+        id: createStorageErrorId("CLICKHOUSE", "UPDATE_WORKFLOW_STATE", "CONTEXT_MISSING"),
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.SYSTEM,
+        text: `Snapshot context is missing for runId ${runId}`
+      });
+    }
+    const updatedSnapshot = { ...snapshot, ...opts };
+    await this.persistWorkflowSnapshot({ workflowName, runId, snapshot: updatedSnapshot });
+    return updatedSnapshot;
   }
   async persistWorkflowSnapshot({
     workflowName,
     runId,
     resourceId,
-    snapshot
+    snapshot,
+    createdAt,
+    updatedAt
   }) {
     try {
-      const currentSnapshot = await this.operations.load({
+      const currentSnapshot = await this.#db.load({
         tableName: TABLE_WORKFLOW_SNAPSHOT,
         keys: { workflow_name: workflowName, run_id: runId }
       });
@@ -1943,14 +2622,14 @@ var WorkflowsStorageClickhouse = class extends WorkflowsStorage {
         ...currentSnapshot,
         resourceId,
         snapshot: JSON.stringify(snapshot),
-        updatedAt: now.toISOString()
+        updatedAt: (updatedAt ?? now).toISOString()
       } : {
         workflow_name: workflowName,
         run_id: runId,
         resourceId,
         snapshot: JSON.stringify(snapshot),
-        createdAt: now.toISOString(),
-        updatedAt: now.toISOString()
+        createdAt: (createdAt ?? now).toISOString(),
+        updatedAt: (updatedAt ?? now).toISOString()
       };
       await this.client.insert({
         table: TABLE_WORKFLOW_SNAPSHOT,
@@ -1980,7 +2659,7 @@ var WorkflowsStorageClickhouse = class extends WorkflowsStorage {
     runId
   }) {
     try {
-      const result = await this.operations.load({
+      const result = await this.#db.load({
         tableName: TABLE_WORKFLOW_SNAPSHOT,
         keys: {
           workflow_name: workflowName,
@@ -2042,7 +2721,7 @@ var WorkflowsStorageClickhouse = class extends WorkflowsStorage {
         values.var_status = status;
       }
       if (resourceId) {
-        const hasResourceId = await this.operations.hasColumn(TABLE_WORKFLOW_SNAPSHOT, "resourceId");
+        const hasResourceId = await this.#db.hasColumn(TABLE_WORKFLOW_SNAPSHOT, "resourceId");
         if (hasResourceId) {
           conditions.push(`resourceId = {var_resourceId:String}`);
           values.var_resourceId = resourceId;
@@ -2184,34 +2863,51 @@ var WorkflowsStorageClickhouse = class extends WorkflowsStorage {
 };
 
 // src/storage/index.ts
+var isClientConfig = (config) => {
+  return "client" in config;
+};
 var ClickhouseStore = class extends MastraStorage {
   db;
   ttl = {};
   stores;
   constructor(config) {
     super({ id: config.id, name: "ClickhouseStore", disableInit: config.disableInit });
-    this.db = createClient({
-      url: config.url,
-      username: config.username,
-      password: config.password,
-      clickhouse_settings: {
-        date_time_input_format: "best_effort",
-        date_time_output_format: "iso",
-        // This is crucial
-        use_client_time_zone: 1,
-        output_format_json_quote_64bit_integers: 0
+    if (isClientConfig(config)) {
+      this.db = config.client;
+    } else {
+      if (!config.url || typeof config.url !== "string" || config.url.trim() === "") {
+        throw new Error("ClickhouseStore: url is required and cannot be empty.");
       }
-    });
+      if (typeof config.username !== "string") {
+        throw new Error("ClickhouseStore: username must be a string.");
+      }
+      if (typeof config.password !== "string") {
+        throw new Error("ClickhouseStore: password must be a string.");
+      }
+      this.db = createClient({
+        url: config.url,
+        username: config.username,
+        password: config.password,
+        clickhouse_settings: {
+          date_time_input_format: "best_effort",
+          date_time_output_format: "iso",
+          // This is crucial
+          use_client_time_zone: 1,
+          output_format_json_quote_64bit_integers: 0
+        }
+      });
+    }
     this.ttl = config.ttl;
-    const operations = new StoreOperationsClickhouse({ client: this.db, ttl: this.ttl });
-    const workflows = new WorkflowsStorageClickhouse({ client: this.db, operations });
-    const scores = new ScoresStorageClickhouse({ client: this.db, operations });
-    const memory = new MemoryStorageClickhouse({ client: this.db, operations });
+    const domainConfig = { client: this.db, ttl: this.ttl };
+    const workflows = new WorkflowsStorageClickhouse(domainConfig);
+    const scores = new ScoresStorageClickhouse(domainConfig);
+    const memory = new MemoryStorageClickhouse(domainConfig);
+    const observability = new ObservabilityStorageClickhouse(domainConfig);
     this.stores = {
-      operations,
       workflows,
       scores,
-      memory
+      memory,
+      observability
     };
   }
   get supports() {
@@ -2220,13 +2916,13 @@ var ClickhouseStore = class extends MastraStorage {
       resourceWorkingMemory: true,
       hasColumn: true,
       createTable: true,
-      deleteMessages: false,
-      listScoresBySpan: true
+      deleteMessages: true,
+      observability: true,
+      indexManagement: false,
+      listScoresBySpan: true,
+      agents: false
     };
   }
-  async batchInsert({ tableName, records }) {
-    await this.stores.operations.batchInsert({ tableName, records });
-  }
   async optimizeTable({ tableName }) {
     try {
       await this.db.command({
@@ -2261,145 +2957,25 @@ var ClickhouseStore = class extends MastraStorage {
       );
     }
   }
-  async createTable({
-    tableName,
-    schema
-  }) {
-    return this.stores.operations.createTable({ tableName, schema });
-  }
-  async dropTable({ tableName }) {
-    return this.stores.operations.dropTable({ tableName });
-  }
-  async alterTable({
-    tableName,
-    schema,
-    ifNotExists
-  }) {
-    return this.stores.operations.alterTable({ tableName, schema, ifNotExists });
-  }
-  async clearTable({ tableName }) {
-    return this.stores.operations.clearTable({ tableName });
-  }
-  async insert({ tableName, record }) {
-    return this.stores.operations.insert({ tableName, record });
-  }
-  async load({ tableName, keys }) {
-    return this.stores.operations.load({ tableName, keys });
-  }
-  async updateWorkflowResults({
-    workflowName,
-    runId,
-    stepId,
-    result,
-    requestContext
-  }) {
-    return this.stores.workflows.updateWorkflowResults({ workflowName, runId, stepId, result, requestContext });
-  }
-  async updateWorkflowState({
-    workflowName,
-    runId,
-    opts
-  }) {
-    return this.stores.workflows.updateWorkflowState({ workflowName, runId, opts });
-  }
-  async persistWorkflowSnapshot({
-    workflowName,
-    runId,
-    resourceId,
-    snapshot
-  }) {
-    return this.stores.workflows.persistWorkflowSnapshot({ workflowName, runId, resourceId, snapshot });
-  }
-  async loadWorkflowSnapshot({
-    workflowName,
-    runId
-  }) {
-    return this.stores.workflows.loadWorkflowSnapshot({ workflowName, runId });
-  }
-  async listWorkflowRuns(args = {}) {
-    return this.stores.workflows.listWorkflowRuns(args);
-  }
-  async getWorkflowRunById({
-    runId,
-    workflowName
-  }) {
-    return this.stores.workflows.getWorkflowRunById({ runId, workflowName });
-  }
-  async deleteWorkflowRunById({ runId, workflowName }) {
-    return this.stores.workflows.deleteWorkflowRunById({ runId, workflowName });
-  }
-  async getThreadById({ threadId }) {
-    return this.stores.memory.getThreadById({ threadId });
-  }
-  async saveThread({ thread }) {
-    return this.stores.memory.saveThread({ thread });
-  }
-  async updateThread({
-    id,
-    title,
-    metadata
-  }) {
-    return this.stores.memory.updateThread({ id, title, metadata });
-  }
-  async deleteThread({ threadId }) {
-    return this.stores.memory.deleteThread({ threadId });
-  }
-  async saveMessages(args) {
-    return this.stores.memory.saveMessages(args);
-  }
-  async updateMessages(args) {
-    return this.stores.memory.updateMessages(args);
-  }
-  async getResourceById({ resourceId }) {
-    return this.stores.memory.getResourceById({ resourceId });
-  }
-  async saveResource({ resource }) {
-    return this.stores.memory.saveResource({ resource });
-  }
-  async updateResource({
-    resourceId,
-    workingMemory,
-    metadata
-  }) {
-    return this.stores.memory.updateResource({ resourceId, workingMemory, metadata });
-  }
-  async getScoreById({ id }) {
-    return this.stores.scores.getScoreById({ id });
-  }
-  async saveScore(score) {
-    return this.stores.scores.saveScore(score);
-  }
-  async listScoresByRunId({
-    runId,
-    pagination
-  }) {
-    return this.stores.scores.listScoresByRunId({ runId, pagination });
-  }
-  async listScoresByEntityId({
-    entityId,
-    entityType,
-    pagination
-  }) {
-    return this.stores.scores.listScoresByEntityId({ entityId, entityType, pagination });
-  }
-  async listScoresByScorerId({
-    scorerId,
-    pagination,
-    entityId,
-    entityType,
-    source
-  }) {
-    return this.stores.scores.listScoresByScorerId({ scorerId, pagination, entityId, entityType, source });
-  }
-  async listScoresBySpan({
-    traceId,
-    spanId,
-    pagination
-  }) {
-    return this.stores.scores.listScoresBySpan({ traceId, spanId, pagination });
-  }
+  /**
+   * Closes the ClickHouse client connection.
+   *
+   * This will close the ClickHouse client, including pre-configured clients.
+   * The store assumes ownership of all clients and manages their lifecycle.
+   */
   async close() {
-    await this.db.close();
+    try {
+      await this.db.close();
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("CLICKHOUSE", "CLOSE", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
+    }
   }
 };