@mastra/clickhouse 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -11,7 +11,7 @@ npm install @mastra/clickhouse
 ## Prerequisites
 
 - Clickhouse server (version 21.12 or higher recommended)
-- Node.js 16 or higher
+- Node.js 22.13.0 or later
 
 ## Usage
 

package/dist/docs/README.md

@@ -0,0 +1,31 @@
+# @mastra/clickhouse Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── storage/ (1 files)
+```
+
+## Version
+
+Package: @mastra/clickhouse
+Version: 1.0.0

package/dist/docs/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: mastra-clickhouse-docs
+description: Documentation for @mastra/clickhouse. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/clickhouse Documentation
+
+> **Version**: 1.0.0
+> **Package**: @mastra/clickhouse
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Storage](storage/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.0.0",
+  "package": "@mastra/clickhouse",
+  "exports": {},
+  "modules": {}
+}

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

@@ -0,0 +1,182 @@
+# Storage API Reference
+
+> API reference for storage - 1 entries
+
+
+---
+
+## Reference: Composite Storage
+
+> Documentation for combining multiple storage backends in Mastra.
+
+`MastraCompositeStore` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
+
+## Installation
+
+`MastraCompositeStore` is included in `@mastra/core`:
+
+```bash
+npm install @mastra/core@beta
+```
+
+You'll also need to install the storage providers you want to compose:
+
+```bash
+npm install @mastra/pg@beta @mastra/libsql@beta
+```
+
+## Storage domains
+
+Mastra organizes storage into five specialized domains, each handling a specific type of data. Each domain can be backed by a different storage adapter, and domain classes are exported from each storage package.
+
+| Domain | Description |
+|--------|-------------|
+| `memory` | Conversation persistence for agents. Stores threads (conversation sessions), messages, resources (user identities), and working memory (persistent context across conversations). |
+| `workflows` | Workflow execution state. When workflows suspend for human input, external events, or scheduled resumption, their state is persisted here to enable resumption after server restarts. |
+| `scores` | Evaluation results from Mastra's evals system. Scores and metrics are persisted here for analysis and comparison over time. |
+| `observability` | Telemetry data including traces and spans. Agent interactions, tool calls, and LLM requests generate spans collected into traces for debugging and performance analysis. |
+| `agents` | Agent configurations for stored agents. Enables agents to be defined and updated at runtime without code deployments. |
+
+## Usage
+
+### Basic composition
+
+Import domain classes directly from each store package and compose them:
+
+```typescript title="src/mastra/index.ts"
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { MemoryLibSQL } from "@mastra/libsql";
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: "composite",
+    domains: {
+      memory: new MemoryLibSQL({ url: "file:./local.db" }),
+      workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+      scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    },
+  }),
+});
+```
+
+### With a default storage
+
+Use `default` to specify a fallback storage, then override specific domains:
+
+```typescript title="src/mastra/index.ts"
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { PostgresStore } from "@mastra/pg";
+import { MemoryLibSQL } from "@mastra/libsql";
+import { Mastra } from "@mastra/core";
+
+const pgStore = new PostgresStore({
+  id: "pg",
+  connectionString: process.env.DATABASE_URL,
+});
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: "composite",
+    default: pgStore,
+    domains: {
+      memory: new MemoryLibSQL({ url: "file:./local.db" }),
+    },
+  }),
+});
+```
+
+## Options
+
+## Initialization
+
+`MastraCompositeStore` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
+
+```typescript title="src/mastra/index.ts"
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { Mastra } from "@mastra/core";
+
+const storage = new MastraCompositeStore({
+  id: "composite",
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+  },
+});
+
+export const mastra = new Mastra({
+  storage, // init() called automatically
+});
+```
+
+If using storage directly, call `init()` explicitly:
+
+```typescript
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryPG } from "@mastra/pg";
+
+const storage = new MastraCompositeStore({
+  id: "composite",
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+  },
+});
+
+await storage.init();
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore("memory");
+const thread = await memoryStore?.getThreadById({ threadId: "..." });
+```
+
+## Use cases
+
+### Separate databases for different workloads
+
+Use a local database for development while keeping production data in a managed service:
+
+```typescript
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { MemoryLibSQL } from "@mastra/libsql";
+
+const storage = new MastraCompositeStore({
+  id: "composite",
+  domains: {
+    // Use local SQLite for development, PostgreSQL for production
+    memory:
+      process.env.NODE_ENV === "development"
+        ? new MemoryLibSQL({ url: "file:./dev.db" })
+        : new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+  },
+});
+```
+
+### Specialized storage for observability
+
+Use a time-series database for traces while keeping other data in PostgreSQL:
+
+```typescript
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
+
+const storage = new MastraCompositeStore({
+  id: "composite",
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    observability: new ObservabilityStorageClickhouse({
+      url: process.env.CLICKHOUSE_URL,
+      username: process.env.CLICKHOUSE_USERNAME,
+      password: process.env.CLICKHOUSE_PASSWORD,
+    }),
+  },
+});
+```