@mastra/clickhouse 0.10.1 → 0.10.2-alpha.1

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/clickhouse@0.10.1-alpha.2 build /home/runner/work/mastra/mastra/stores/clickhouse
+> @mastra/clickhouse@0.10.2-alpha.1 build /home/runner/work/mastra/mastra/stores/clickhouse
 > tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
-CLI tsup v8.4.0
+CLI tsup v8.5.0
 TSC Build start
-TSC ⚡️ Build success in 8613ms
+TSC ⚡️ Build success in 8294ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/stores/clickhouse/dist/_tsup-dts-rollup.d.ts
 Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/stores/clickhouse/dist/_tsup-dts-rollup.d.cts
-DTS ⚡️ Build success in 11358ms
+DTS ⚡️ Build success in 11634ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.js 28.23 KB
-ESM ⚡️ Build success in 942ms
-CJS dist/index.cjs 28.49 KB
-CJS ⚡️ Build success in 943ms
+ESM dist/index.js 30.35 KB
+ESM ⚡️ Build success in 1068ms
+CJS dist/index.cjs 30.60 KB
+CJS ⚡️ Build success in 1069ms

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @mastra/clickhouse
 
+## 0.10.2-alpha.1
+
+### Patch Changes
+
+- 925ab94: added paginated functions to base class and added boilerplate and updated imports
+- Updated dependencies [925ab94]
+  - @mastra/core@0.10.4-alpha.3
+
+## 0.10.2-alpha.0
+
+### Patch Changes
+
+- dffb67b: updated stores to add alter table and change tests
+- Updated dependencies [f6fd25f]
+- Updated dependencies [dffb67b]
+- Updated dependencies [f1309d3]
+- Updated dependencies [f7f8293]
+  - @mastra/core@0.10.4-alpha.1
+
 ## 0.10.1
 
 ### Patch Changes

package/dist/_tsup-dts-rollup.d.cts

@@ -1,13 +1,16 @@
 import type { ClickHouseClient } from '@clickhouse/client';
 import type { EvalRow } from '@mastra/core/storage';
 import type { MastraMessageV1 } from '@mastra/core/memory';
-import type { MastraMessageV2 } from '@mastra/core/agent';
+import type { MastraMessageV2 } from '@mastra/core/memory';
 import { MastraStorage } from '@mastra/core/storage';
+import type { PaginationInfo } from '@mastra/core/storage';
 import type { StorageColumn } from '@mastra/core/storage';
 import type { StorageGetMessagesArg } from '@mastra/core/storage';
+import type { StorageGetTracesArg } from '@mastra/core/storage';
 import type { StorageThreadType } from '@mastra/core/memory';
 import type { TABLE_NAMES } from '@mastra/core/storage';
 import { TABLE_SCHEMAS } from '@mastra/core/storage';
+import type { Trace } from '@mastra/core/telemetry';
 import type { WorkflowRun } from '@mastra/core/storage';
 import type { WorkflowRuns } from '@mastra/core/storage';
 import type { WorkflowRunState } from '@mastra/core/workflows';
@@ -66,6 +69,18 @@ declare class ClickhouseStore extends MastraStorage {
         tableName: TABLE_NAMES;
         schema: Record<string, StorageColumn>;
     }): Promise<void>;
+    protected getSqlType(type: StorageColumn['type']): string;
+    /**
+     * Alters table schema to add columns if they don't exist
+     * @param tableName Name of the table
+     * @param schema Schema of the table
+     * @param ifNotExists Array of column names to add if they don't exist
+     */
+    alterTable({ tableName, schema, ifNotExists, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+        ifNotExists: string[];
+    }): Promise<void>;
     clearTable({ tableName }: {
         tableName: TABLE_NAMES;
     }): Promise<void>;
@@ -131,6 +146,19 @@ declare class ClickhouseStore extends MastraStorage {
         workflowName?: string;
     }): Promise<WorkflowRun | null>;
     private hasColumn;
+    getTracesPaginated(_args: StorageGetTracesArg): Promise<PaginationInfo & {
+        traces: Trace[];
+    }>;
+    getThreadsByResourceIdPaginated(_args: {
+        resourceId: string;
+        page?: number;
+        perPage?: number;
+    }): Promise<PaginationInfo & {
+        threads: StorageThreadType[];
+    }>;
+    getMessagesPaginated(_args: StorageGetMessagesArg): Promise<PaginationInfo & {
+        messages: MastraMessageV1[] | MastraMessageV2[];
+    }>;
     close(): Promise<void>;
 }
 export { ClickhouseStore }

package/dist/_tsup-dts-rollup.d.ts

@@ -1,13 +1,16 @@
 import type { ClickHouseClient } from '@clickhouse/client';
 import type { EvalRow } from '@mastra/core/storage';
 import type { MastraMessageV1 } from '@mastra/core/memory';
-import type { MastraMessageV2 } from '@mastra/core/agent';
+import type { MastraMessageV2 } from '@mastra/core/memory';
 import { MastraStorage } from '@mastra/core/storage';
+import type { PaginationInfo } from '@mastra/core/storage';
 import type { StorageColumn } from '@mastra/core/storage';
 import type { StorageGetMessagesArg } from '@mastra/core/storage';
+import type { StorageGetTracesArg } from '@mastra/core/storage';
 import type { StorageThreadType } from '@mastra/core/memory';
 import type { TABLE_NAMES } from '@mastra/core/storage';
 import { TABLE_SCHEMAS } from '@mastra/core/storage';
+import type { Trace } from '@mastra/core/telemetry';
 import type { WorkflowRun } from '@mastra/core/storage';
 import type { WorkflowRuns } from '@mastra/core/storage';
 import type { WorkflowRunState } from '@mastra/core/workflows';
@@ -66,6 +69,18 @@ declare class ClickhouseStore extends MastraStorage {
         tableName: TABLE_NAMES;
         schema: Record<string, StorageColumn>;
     }): Promise<void>;
+    protected getSqlType(type: StorageColumn['type']): string;
+    /**
+     * Alters table schema to add columns if they don't exist
+     * @param tableName Name of the table
+     * @param schema Schema of the table
+     * @param ifNotExists Array of column names to add if they don't exist
+     */
+    alterTable({ tableName, schema, ifNotExists, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+        ifNotExists: string[];
+    }): Promise<void>;
     clearTable({ tableName }: {
         tableName: TABLE_NAMES;
     }): Promise<void>;
@@ -131,6 +146,19 @@ declare class ClickhouseStore extends MastraStorage {
         workflowName?: string;
     }): Promise<WorkflowRun | null>;
     private hasColumn;
+    getTracesPaginated(_args: StorageGetTracesArg): Promise<PaginationInfo & {
+        traces: Trace[];
+    }>;
+    getThreadsByResourceIdPaginated(_args: {
+        resourceId: string;
+        page?: number;
+        perPage?: number;
+    }): Promise<PaginationInfo & {
+        threads: StorageThreadType[];
+    }>;
+    getMessagesPaginated(_args: StorageGetMessagesArg): Promise<PaginationInfo & {
+        messages: MastraMessageV1[] | MastraMessageV2[];
+    }>;
     close(): Promise<void>;
 }
 export { ClickhouseStore }

package/dist/index.cjs

@@ -267,6 +267,61 @@ var ClickhouseStore = class extends storage.MastraStorage {
       throw error;
     }
   }
+  getSqlType(type) {
+    switch (type) {
+      case "text":
+        return "String";
+      case "timestamp":
+        return "DateTime64(3)";
+      case "integer":
+      case "bigint":
+        return "Int64";
+      case "jsonb":
+        return "String";
+      default:
+        return super.getSqlType(type);
+    }
+  }
+  /**
+   * Alters table schema to add columns if they don't exist
+   * @param tableName Name of the table
+   * @param schema Schema of the table
+   * @param ifNotExists Array of column names to add if they don't exist
+   */
+  async alterTable({
+    tableName,
+    schema,
+    ifNotExists
+  }) {
+    try {
+      const describeSql = `DESCRIBE TABLE ${tableName}`;
+      const result = await this.db.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 ? this.getDefaultValue(columnDef.type) : "";
+          const alterSql = `ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS "${columnName}" ${sqlType} ${defaultValue}`.trim();
+          await this.db.query({
+            query: alterSql
+          });
+          this.logger?.debug?.(`Added column ${columnName} to table ${tableName}`);
+        }
+      }
+    } catch (error) {
+      this.logger?.error?.(
+        `Error altering table ${tableName}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      throw new Error(`Failed to alter table ${tableName}: ${error}`);
+    }
+  }
   async clearTable({ tableName }) {
     try {
       await this.db.query({
@@ -857,6 +912,15 @@ var ClickhouseStore = class extends storage.MastraStorage {
     const columns = await result.json();
     return columns.some((c) => c.name === column);
   }
+  async getTracesPaginated(_args) {
+    throw new Error("Method not implemented.");
+  }
+  async getThreadsByResourceIdPaginated(_args) {
+    throw new Error("Method not implemented.");
+  }
+  async getMessagesPaginated(_args) {
+    throw new Error("Method not implemented.");
+  }
   async close() {
     await this.db.close();
   }

package/dist/index.js

@@ -265,6 +265,61 @@ var ClickhouseStore = class extends MastraStorage {
       throw error;
     }
   }
+  getSqlType(type) {
+    switch (type) {
+      case "text":
+        return "String";
+      case "timestamp":
+        return "DateTime64(3)";
+      case "integer":
+      case "bigint":
+        return "Int64";
+      case "jsonb":
+        return "String";
+      default:
+        return super.getSqlType(type);
+    }
+  }
+  /**
+   * Alters table schema to add columns if they don't exist
+   * @param tableName Name of the table
+   * @param schema Schema of the table
+   * @param ifNotExists Array of column names to add if they don't exist
+   */
+  async alterTable({
+    tableName,
+    schema,
+    ifNotExists
+  }) {
+    try {
+      const describeSql = `DESCRIBE TABLE ${tableName}`;
+      const result = await this.db.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 ? this.getDefaultValue(columnDef.type) : "";
+          const alterSql = `ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS "${columnName}" ${sqlType} ${defaultValue}`.trim();
+          await this.db.query({
+            query: alterSql
+          });
+          this.logger?.debug?.(`Added column ${columnName} to table ${tableName}`);
+        }
+      }
+    } catch (error) {
+      this.logger?.error?.(
+        `Error altering table ${tableName}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      throw new Error(`Failed to alter table ${tableName}: ${error}`);
+    }
+  }
   async clearTable({ tableName }) {
     try {
       await this.db.query({
@@ -855,6 +910,15 @@ var ClickhouseStore = class extends MastraStorage {
     const columns = await result.json();
     return columns.some((c) => c.name === column);
   }
+  async getTracesPaginated(_args) {
+    throw new Error("Method not implemented.");
+  }
+  async getThreadsByResourceIdPaginated(_args) {
+    throw new Error("Method not implemented.");
+  }
+  async getMessagesPaginated(_args) {
+    throw new Error("Method not implemented.");
+  }
   async close() {
     await this.db.close();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/clickhouse",
-  "version": "0.10.1",
+  "version": "0.10.2-alpha.1",
   "description": "Clickhouse provider for Mastra - includes db storage capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -23,14 +23,15 @@
     "@clickhouse/client": "^1.11.0"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.52.5",
-    "@types/node": "^20.17.27",
-    "eslint": "^9.23.0",
-    "tsup": "^8.4.0",
+    "@microsoft/api-extractor": "^7.52.8",
+    "@types/node": "^20.17.57",
+    "eslint": "^9.28.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.8.2",
-    "vitest": "^3.1.2",
-    "@mastra/core": "0.10.2",
-    "@internal/lint": "0.0.8"
+    "vitest": "^3.2.2",
+    "@internal/lint": "0.0.10",
+    "@internal/storage-test-utils": "0.0.6",
+    "@mastra/core": "0.10.4-alpha.3"
   },
   "peerDependencies": {
     "@mastra/core": "^0.10.2-alpha.0"

package/src/storage/index.test.ts

@@ -1,9 +1,16 @@
 import { randomUUID } from 'crypto';
-import type { MastraMessageV1, WorkflowRunState } from '@mastra/core';
+import {
+  createSampleMessageV1,
+  createSampleThread,
+  createSampleWorkflowSnapshot,
+  checkWorkflowSnapshot,
+} from '@internal/storage-test-utils';
+import type { MastraMessageV1, StorageColumn, WorkflowRunState } from '@mastra/core';
+import type { TABLE_NAMES } from '@mastra/core/storage';
 import { TABLE_THREADS, TABLE_MESSAGES, TABLE_WORKFLOW_SNAPSHOT } from '@mastra/core/storage';
 import { describe, it, expect, beforeAll, beforeEach, afterAll, vi, afterEach } from 'vitest';
 
-import { ClickhouseStore } from '.';
+import { ClickhouseStore, TABLE_ENGINES } from '.';
 import type { ClickhouseConfig } from '.';
 
 vi.setConfig({ testTimeout: 60_000, hookTimeout: 60_000 });
@@ -24,33 +31,6 @@ const TEST_CONFIG: ClickhouseConfig = {
   },
 };
 
-// Sample test data factory functions
-const createSampleThread = () => ({
-  id: `thread-${randomUUID()}`,
-  resourceId: `clickhouse-test`,
-  title: 'Test Thread',
-  createdAt: new Date(),
-  updatedAt: new Date(),
-  metadata: { key: 'value' },
-});
-
-let role = `user`;
-const getRole = () => {
-  if (role === `user`) role = `assistant`;
-  else role = `user`;
-  return role as 'user' | 'assistant';
-};
-
-const createSampleMessage = (threadId: string, createdAt: Date = new Date()): MastraMessageV1 => ({
-  id: `msg-${randomUUID()}`,
-  resourceId: `clickhouse-test`,
-  role: getRole(),
-  type: 'text',
-  threadId,
-  content: 'Hello',
-  createdAt,
-});
-
 const createSampleTrace = () => ({
   id: `trace-${randomUUID()}`,
   name: 'Test Trace',
@@ -66,39 +46,6 @@ const createSampleEval = () => ({
   createdAt: new Date(),
 });
 
-const createSampleWorkflowSnapshot = (status: WorkflowRunState['context']['steps']['status'], createdAt?: Date) => {
-  const runId = `run-${randomUUID()}`;
-  const stepId = `step-${randomUUID()}`;
-  const timestamp = createdAt || new Date();
-  const snapshot = {
-    result: { success: true },
-    value: {},
-    context: {
-      [stepId]: {
-        status,
-        payload: {},
-        error: undefined,
-        startedAt: timestamp.getTime(),
-        endedAt: new Date(timestamp.getTime() + 15000).getTime(),
-      },
-      input: {},
-    },
-    serializedStepGraph: [],
-    activePaths: [],
-    suspendedPaths: {},
-    runId,
-    timestamp: timestamp.getTime(),
-  } as unknown as WorkflowRunState;
-  return { snapshot, runId, stepId };
-};
-
-const checkWorkflowSnapshot = (snapshot: WorkflowRunState | string, stepId: string, status: string) => {
-  if (typeof snapshot === 'string') {
-    throw new Error('Expected WorkflowRunState, got string');
-  }
-  expect(snapshot.context?.[stepId]?.status).toBe(status);
-};
-
 describe('ClickhouseStore', () => {
   let store: ClickhouseStore;
 
@@ -171,7 +118,10 @@ describe('ClickhouseStore', () => {
       await store.saveThread({ thread });
 
       // Add some messages
-      const messages = [createSampleMessage(thread.id), createSampleMessage(thread.id)];
+      const messages = [
+        createSampleMessageV1({ threadId: thread.id, resourceId: 'clickhouse-test' }),
+        createSampleMessageV1({ threadId: thread.id, resourceId: 'clickhouse-test' }),
+      ];
       await store.saveMessages({ messages });
 
       await store.deleteThread({ threadId: thread.id });
@@ -191,8 +141,12 @@ describe('ClickhouseStore', () => {
       await store.saveThread({ thread });
 
       const messages = [
-        createSampleMessage(thread.id, new Date(Date.now() - 1000 * 60 * 60 * 24)),
-        createSampleMessage(thread.id),
+        createSampleMessageV1({
+          threadId: thread.id,
+          createdAt: new Date(Date.now() - 1000 * 60 * 60 * 24),
+          resourceId: 'clickhouse-test',
+        }),
+        createSampleMessageV1({ threadId: thread.id, resourceId: 'clickhouse-test' }),
       ];
 
       // Save messages
@@ -218,23 +172,35 @@ describe('ClickhouseStore', () => {
       const thread = createSampleThread();
       await store.saveThread({ thread });
 
-      const messages: MastraMessageV1[] = [
+      const messages = [
         {
-          ...createSampleMessage(thread.id, new Date(Date.now() - 1000 * 3)),
-          content: [{ type: 'text', text: 'First' }],
+          ...createSampleMessageV1({
+            threadId: thread.id,
+            createdAt: new Date(Date.now() - 1000 * 3),
+            content: 'First',
+            resourceId: 'clickhouse-test',
+          }),
           role: 'user',
         },
         {
-          ...createSampleMessage(thread.id, new Date(Date.now() - 1000 * 2)),
-          content: [{ type: 'text', text: 'Second' }],
+          ...createSampleMessageV1({
+            threadId: thread.id,
+            createdAt: new Date(Date.now() - 1000 * 2),
+            content: 'Second',
+            resourceId: 'clickhouse-test',
+          }),
           role: 'assistant',
         },
         {
-          ...createSampleMessage(thread.id, new Date(Date.now() - 1000 * 1)),
-          content: [{ type: 'text', text: 'Third' }],
+          ...createSampleMessageV1({
+            threadId: thread.id,
+            createdAt: new Date(Date.now() - 1000 * 1),
+            content: 'Third',
+            resourceId: 'clickhouse-test',
+          }),
           role: 'user',
         },
-      ];
+      ] as MastraMessageV1[];
 
       await store.saveMessages({ messages });
 
@@ -248,13 +214,107 @@ describe('ClickhouseStore', () => {
       });
     }, 10e3);
 
+    // it('should retrieve messages w/ next/prev messages by message id + resource id', async () => {
+    //   const messages: MastraMessageV2[] = [
+    //     createSampleMessageV2({ threadId: 'thread-one', content: 'First', resourceId: 'cross-thread-resource' }),
+    //     createSampleMessageV2({ threadId: 'thread-one', content: 'Second', resourceId: 'cross-thread-resource' }),
+    //     createSampleMessageV2({ threadId: 'thread-one', content: 'Third', resourceId: 'cross-thread-resource' }),
+
+    //     createSampleMessageV2({ threadId: 'thread-two', content: 'Fourth', resourceId: 'cross-thread-resource' }),
+    //     createSampleMessageV2({ threadId: 'thread-two', content: 'Fifth', resourceId: 'cross-thread-resource' }),
+    //     createSampleMessageV2({ threadId: 'thread-two', content: 'Sixth', resourceId: 'cross-thread-resource' }),
+
+    //     createSampleMessageV2({ threadId: 'thread-three', content: 'Seventh', resourceId: 'other-resource' }),
+    //     createSampleMessageV2({ threadId: 'thread-three', content: 'Eighth', resourceId: 'other-resource' }),
+    //   ];
+
+    //   await store.saveMessages({ messages: messages, format: 'v2' });
+
+    //   const retrievedMessages = await store.getMessages({ threadId: 'thread-one', format: 'v2' });
+    //   expect(retrievedMessages).toHaveLength(3);
+    //   expect(retrievedMessages.map((m: any) => m.content.parts[0].text)).toEqual(['First', 'Second', 'Third']);
+
+    //   const retrievedMessages2 = await store.getMessages({ threadId: 'thread-two', format: 'v2' });
+    //   expect(retrievedMessages2).toHaveLength(3);
+    //   expect(retrievedMessages2.map((m: any) => m.content.parts[0].text)).toEqual(['Fourth', 'Fifth', 'Sixth']);
+
+    //   const retrievedMessages3 = await store.getMessages({ threadId: 'thread-three', format: 'v2' });
+    //   expect(retrievedMessages3).toHaveLength(2);
+    //   expect(retrievedMessages3.map((m: any) => m.content.parts[0].text)).toEqual(['Seventh', 'Eighth']);
+
+    //   const crossThreadMessages = await store.getMessages({
+    //     threadId: 'thread-doesnt-exist',
+    //     resourceId: 'cross-thread-resource',
+    //     format: 'v2',
+    //     selectBy: {
+    //       last: 0,
+    //       include: [
+    //         {
+    //           id: messages[1].id,
+    //           withNextMessages: 2,
+    //           withPreviousMessages: 2,
+    //         },
+    //         {
+    //           id: messages[4].id,
+    //           withPreviousMessages: 2,
+    //           withNextMessages: 2,
+    //         },
+    //       ],
+    //     },
+    //   });
+
+    //   expect(crossThreadMessages).toHaveLength(6);
+    //   expect(crossThreadMessages.filter(m => m.threadId === `thread-one`)).toHaveLength(3);
+    //   expect(crossThreadMessages.filter(m => m.threadId === `thread-two`)).toHaveLength(3);
+
+    //   const crossThreadMessages2 = await store.getMessages({
+    //     threadId: 'thread-one',
+    //     resourceId: 'cross-thread-resource',
+    //     format: 'v2',
+    //     selectBy: {
+    //       last: 0,
+    //       include: [
+    //         {
+    //           id: messages[4].id,
+    //           withPreviousMessages: 1,
+    //           withNextMessages: 30,
+    //         },
+    //       ],
+    //     },
+    //   });
+
+    //   expect(crossThreadMessages2).toHaveLength(3);
+    //   expect(crossThreadMessages2.filter(m => m.threadId === `thread-one`)).toHaveLength(0);
+    //   expect(crossThreadMessages2.filter(m => m.threadId === `thread-two`)).toHaveLength(3);
+
+    //   const crossThreadMessages3 = await store.getMessages({
+    //     threadId: 'thread-two',
+    //     resourceId: 'cross-thread-resource',
+    //     format: 'v2',
+    //     selectBy: {
+    //       last: 0,
+    //       include: [
+    //         {
+    //           id: messages[1].id,
+    //           withNextMessages: 1,
+    //           withPreviousMessages: 1,
+    //         },
+    //       ],
+    //     },
+    //   });
+
+    //   expect(crossThreadMessages3).toHaveLength(3);
+    //   expect(crossThreadMessages3.filter(m => m.threadId === `thread-one`)).toHaveLength(3);
+    //   expect(crossThreadMessages3.filter(m => m.threadId === `thread-two`)).toHaveLength(0);
+    // });
+
     // it('should rollback on error during message save', async () => {
     //   const thread = createSampleThread();
     //   await store.saveThread({ thread });
 
     //   const messages = [
-    //     createSampleMessage(thread.id),
-    //     { ...createSampleMessage(thread.id), id: null }, // This will cause an error
+    //     createSampleMessageV1({ threadId: thread.id }),
+    //     { ...createSampleMessageV1({ threadId: thread.id }), id: null }, // This will cause an error
     //   ];
 
     //   await expect(store.saveMessages({ messages })).rejects.toThrow();
@@ -842,6 +902,100 @@ describe('ClickhouseStore', () => {
     });
   });
 
+  describe('alterTable', () => {
+    const TEST_TABLE = 'test_alter_table';
+    const BASE_SCHEMA = {
+      id: { type: 'integer', primaryKey: true, nullable: false },
+      name: { type: 'text', nullable: true },
+      createdAt: { type: 'timestamp', nullable: false },
+      updatedAt: { type: 'timestamp', nullable: false },
+    } as Record<string, StorageColumn>;
+
+    TABLE_ENGINES[TEST_TABLE] = 'MergeTree()';
+
+    beforeEach(async () => {
+      await store.createTable({ tableName: TEST_TABLE as TABLE_NAMES, schema: BASE_SCHEMA });
+    });
+
+    afterEach(async () => {
+      await store.clearTable({ tableName: TEST_TABLE as TABLE_NAMES });
+    });
+
+    it('adds a new column to an existing table', async () => {
+      await store.alterTable({
+        tableName: TEST_TABLE as TABLE_NAMES,
+        schema: { ...BASE_SCHEMA, age: { type: 'integer', nullable: true } },
+        ifNotExists: ['age'],
+      });
+
+      await store.insert({
+        tableName: TEST_TABLE as TABLE_NAMES,
+        record: { id: 1, name: 'Alice', age: 42, createdAt: new Date(), updatedAt: new Date() },
+      });
+
+      const row = await store.load<{ id: string; name: string; age?: number }>({
+        tableName: TEST_TABLE as TABLE_NAMES,
+        keys: { id: '1' },
+      });
+      expect(row?.age).toBe(42);
+    });
+
+    it('is idempotent when adding an existing column', async () => {
+      await store.alterTable({
+        tableName: TEST_TABLE as TABLE_NAMES,
+        schema: { ...BASE_SCHEMA, foo: { type: 'text', nullable: true } },
+        ifNotExists: ['foo'],
+      });
+      // Add the column again (should not throw)
+      await expect(
+        store.alterTable({
+          tableName: TEST_TABLE as TABLE_NAMES,
+          schema: { ...BASE_SCHEMA, foo: { type: 'text', nullable: true } },
+          ifNotExists: ['foo'],
+        }),
+      ).resolves.not.toThrow();
+    });
+
+    it('should add a default value to a column when using not null', async () => {
+      await store.insert({
+        tableName: TEST_TABLE as TABLE_NAMES,
+        record: { id: 1, name: 'Bob', createdAt: new Date(), updatedAt: new Date() },
+      });
+
+      await expect(
+        store.alterTable({
+          tableName: TEST_TABLE as TABLE_NAMES,
+          schema: { ...BASE_SCHEMA, text_column: { type: 'text', nullable: false } },
+          ifNotExists: ['text_column'],
+        }),
+      ).resolves.not.toThrow();
+
+      await expect(
+        store.alterTable({
+          tableName: TEST_TABLE as TABLE_NAMES,
+          schema: { ...BASE_SCHEMA, timestamp_column: { type: 'timestamp', nullable: false } },
+          ifNotExists: ['timestamp_column'],
+        }),
+      ).resolves.not.toThrow();
+
+      await expect(
+        store.alterTable({
+          tableName: TEST_TABLE as TABLE_NAMES,
+          schema: { ...BASE_SCHEMA, bigint_column: { type: 'bigint', nullable: false } },
+          ifNotExists: ['bigint_column'],
+        }),
+      ).resolves.not.toThrow();
+
+      await expect(
+        store.alterTable({
+          tableName: TEST_TABLE as TABLE_NAMES,
+          schema: { ...BASE_SCHEMA, jsonb_column: { type: 'jsonb', nullable: false } },
+          ifNotExists: ['jsonb_column'],
+        }),
+      ).resolves.not.toThrow();
+    });
+  });
+
   afterAll(async () => {
     await store.close();
   });

package/src/storage/index.ts

@@ -1,9 +1,8 @@
 import type { ClickHouseClient } from '@clickhouse/client';
 import { createClient } from '@clickhouse/client';
 import { MessageList } from '@mastra/core/agent';
-import type { MastraMessageV2 } from '@mastra/core/agent';
 import type { MetricResult, TestInfo } from '@mastra/core/eval';
-import type { MastraMessageV1, StorageThreadType } from '@mastra/core/memory';
+import type { MastraMessageV1, MastraMessageV2, StorageThreadType } from '@mastra/core/memory';
 import {
   MastraStorage,
   TABLE_EVALS,
@@ -15,12 +14,15 @@ import {
 } from '@mastra/core/storage';
 import type {
   EvalRow,
+  PaginationInfo,
   StorageColumn,
   StorageGetMessagesArg,
   TABLE_NAMES,
   WorkflowRun,
   WorkflowRuns,
+  StorageGetTracesArg,
 } from '@mastra/core/storage';
+import type { Trace } from '@mastra/core/telemetry';
 import type { WorkflowRunState } from '@mastra/core/workflows';
 
 function safelyParseJSON(jsonString: string): any {
@@ -371,6 +373,73 @@ export class ClickhouseStore extends MastraStorage {
     }
   }
 
+  protected getSqlType(type: StorageColumn['type']): string {
+    switch (type) {
+      case 'text':
+        return 'String';
+      case 'timestamp':
+        return 'DateTime64(3)';
+      case 'integer':
+      case 'bigint':
+        return 'Int64';
+      case 'jsonb':
+        return 'String';
+      default:
+        return super.getSqlType(type); // fallback to base implementation
+    }
+  }
+
+  /**
+   * Alters table schema to add columns if they don't exist
+   * @param tableName Name of the table
+   * @param schema Schema of the table
+   * @param ifNotExists Array of column names to add if they don't exist
+   */
+  async alterTable({
+    tableName,
+    schema,
+    ifNotExists,
+  }: {
+    tableName: TABLE_NAMES;
+    schema: Record<string, StorageColumn>;
+    ifNotExists: string[];
+  }): Promise<void> {
+    try {
+      // 1. Get existing columns
+      const describeSql = `DESCRIBE TABLE ${tableName}`;
+      const result = await this.db.query({
+        query: describeSql,
+      });
+      const rows = await result.json();
+      const existingColumnNames = new Set(rows.data.map((row: any) => row.name.toLowerCase()));
+
+      // 2. Add missing columns
+      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) : '';
+          // Use backticks or double quotes as needed for identifiers
+          const alterSql =
+            `ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS "${columnName}" ${sqlType} ${defaultValue}`.trim();
+
+          await this.db.query({
+            query: alterSql,
+          });
+          this.logger?.debug?.(`Added column ${columnName} to table ${tableName}`);
+        }
+      }
+    } catch (error) {
+      this.logger?.error?.(
+        `Error altering table ${tableName}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      throw new Error(`Failed to alter table ${tableName}: ${error}`);
+    }
+  }
+
   async clearTable({ tableName }: { tableName: TABLE_NAMES }): Promise<void> {
     try {
       await this.db.query({
@@ -1069,6 +1138,24 @@ export class ClickhouseStore extends MastraStorage {
     return columns.some(c => c.name === column);
   }
 
+  async getTracesPaginated(_args: StorageGetTracesArg): Promise<PaginationInfo & { traces: Trace[] }> {
+    throw new Error('Method not implemented.');
+  }
+
+  async getThreadsByResourceIdPaginated(_args: {
+    resourceId: string;
+    page?: number;
+    perPage?: number;
+  }): Promise<PaginationInfo & { threads: StorageThreadType[] }> {
+    throw new Error('Method not implemented.');
+  }
+
+  async getMessagesPaginated(
+    _args: StorageGetMessagesArg,
+  ): Promise<PaginationInfo & { messages: MastraMessageV1[] | MastraMessageV2[] }> {
+    throw new Error('Method not implemented.');
+  }
+
   async close(): Promise<void> {
     await this.db.close();
   }