@mastra/clickhouse 0.10.1 → 0.10.2-alpha.0

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.0 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 9329ms
 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 11005ms
 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.08 KB
+ESM ⚡️ Build success in 1046ms
+CJS dist/index.cjs 30.33 KB
+CJS ⚡️ Build success in 1040ms

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @mastra/clickhouse
 
+## 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

@@ -66,6 +66,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>;

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

@@ -66,6 +66,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>;

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({

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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/clickhouse",
-  "version": "0.10.1",
+  "version": "0.10.2-alpha.0",
   "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.1"
   },
   "peerDependencies": {
     "@mastra/core": "^0.10.2-alpha.0"

package/src/storage/index.test.ts

@@ -1,9 +1,11 @@
 import { randomUUID } from 'crypto';
-import type { MastraMessageV1, WorkflowRunState } from '@mastra/core';
+import { createSampleMessageV1, createSampleThread, createSampleWorkflowSnapshot } 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 +26,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,32 +41,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');
@@ -171,7 +120,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 +143,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
@@ -220,18 +176,30 @@ describe('ClickhouseStore', () => {
 
       const messages: MastraMessageV1[] = [
         {
-          ...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',
         },
       ];
@@ -253,8 +221,8 @@ describe('ClickhouseStore', () => {
     //   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 +810,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

@@ -371,6 +371,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({