@mastra/clickhouse 1.24.0-alpha.1 → 1.25.0-alpha.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-clickhouse
 description: Documentation for @mastra/clickhouse. Use when working with @mastra/clickhouse APIs, configuration, or implementation.
 metadata:
   package: "@mastra/clickhouse"
-  version: "1.24.0-alpha.1"
+  version: "1.25.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.24.0-alpha.1",
+  "version": "1.25.0-alpha.0",
   "package": "@mastra/clickhouse",
   "exports": {},
   "modules": {}

package/dist/docs/references/integrations-databases-clickhouse.md

@@ -232,6 +232,19 @@ The same `client` form is accepted by `ObservabilityStorageClickhouse` and `Obse
 
 `ClickhouseStore` also accepts every option from `ClickHouseClientConfigOptions` (such as `database`, `request_timeout`, `compression`, `keep_alive`, and `max_open_connections`).
 
+`ClickhouseStore` and `ObservabilityStorageClickhouseVNext` apply `clickhouse_settings` to every query they run. On ClickHouse services that keep data in object storage, such as ClickHouse Cloud, limiting read-ahead lowers the memory each observability query uses, but queries that miss the local cache can run slower:
+
+```typescript
+const observabilityStore = new ObservabilityStorageClickhouseVNext({
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+  clickhouse_settings: {
+    filesystem_prefetches_limit: 8,
+  },
+})
+```
+
 ### Replicated clusters
 
 Use `replication` when Mastra writes to a multi-replica ClickHouse cluster through a load balancer.

package/dist/docs/references/reference-storage-composite.md

@@ -210,6 +210,40 @@ export const mastra = new Mastra({
 
 **domains.experiments** (`ExperimentsStorage`): Storage for experiment runs and per-item experiment results.
 
+**domains.workflowDefinitions** (`WorkflowDefinitionsStorage`): Storage for persisted workflow definitions.
+
+**domains.promptBlocks** (`PromptBlocksStorage`): Storage for stored prompt blocks and their versions.
+
+**domains.scorerDefinitions** (`ScorerDefinitionsStorage`): Storage for stored scorer definitions and their versions.
+
+**domains.mcpClients** (`MCPClientsStorage`): Storage for stored MCP client configurations and their versions.
+
+**domains.mcpServers** (`MCPServersStorage`): Storage for stored MCP server configurations and their versions.
+
+**domains.workspaces** (`WorkspacesStorage`): Storage for stored workspace configurations and their versions.
+
+**domains.skills** (`SkillsStorage`): Storage for stored skill definitions and their versions.
+
+**domains.favorites** (`FavoritesStorage`): Storage for user favorites on stored entities.
+
+**domains.blobs** (`BlobStore`): Content-addressable storage for file contents used by skill versioning.
+
+**domains.backgroundTasks** (`BackgroundTasksStorage`): Storage for background task state.
+
+**domains.schedules** (`SchedulesStorage`): Storage for schedules that the scheduler fires.
+
+**domains.channels** (`ChannelsStorage`): Storage for channel installations and configuration.
+
+**domains.harness** (`HarnessStorage`): Storage for harness sessions.
+
+**domains.toolProviderConnections** (`ToolProviderConnectionsStorage`): Storage for authorized tool provider connections.
+
+**domains.notifications** (`NotificationsStorage`): Storage for notifications and their delivery state.
+
+**domains.threadState** (`ThreadStateStorage`): Storage for per-thread agent state, such as task lists and goals.
+
+**domains.knowledge** (`KnowledgeStorage`): Storage for knowledge nodes and records. Experimental.
+
 ## Initialization
 
 `MastraCompositeStore` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:

package/dist/docs/references/reference-storage-retention.md

@@ -95,29 +95,32 @@ Set the `retention` field on the store config.
 
 Each domain specifies its age-prunable tables and the timestamp column that anchors comparison, chosen so `maxAge` matches the meaning of the data. Append-only logs use creation time, live state uses last activity, and jobs or runs use completion time so in-flight work isn't pruned.
 
-| Domain            | Table key          | Anchor column    | `maxAge` measures                                                |
-| ----------------- | ------------------ | ---------------- | ---------------------------------------------------------------- |
-| `memory`          | `threads`          | `createdAt`      | Thread age                                                       |
-| `memory`          | `messages`         | `createdAt`      | Message age                                                      |
-| `memory`          | `resources`        | `createdAt`      | Resource age                                                     |
-| `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives              |
-| `observability`   | `spans`            | `startedAt`      | Span age                                                         |
-| `observability`   | `metrics`          | `timestamp`      | Metric event age (vNext only)                                    |
-| `observability`   | `logs`             | `timestamp`      | Log event age (vNext only)                                       |
-| `observability`   | `scores`           | `timestamp`      | Score event age (vNext only)                                     |
-| `observability`   | `feedback`         | `timestamp`      | Feedback event age (vNext only)                                  |
-| `scores`          | `scorers`          | `createdAt`      | Score record age                                                 |
-| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive          |
-| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned |
-| `experiments`     | `experiments`      | `completedAt`    | Time since completion, running experiments are never pruned      |
-| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                 |
-| `harness`         | `sessions`         | `createdAt`      | Session record age                                               |
-| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                               |
+| Domain            | Table key          | Anchor column    | `maxAge` measures                                                                                                                |
+| ----------------- | ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `memory`          | `threads`          | `createdAt`      | Thread age                                                                                                                       |
+| `memory`          | `messages`         | `createdAt`      | Message age                                                                                                                      |
+| `memory`          | `resources`        | `createdAt`      | Resource age                                                                                                                     |
+| `memory`          | `runFences`        | `retiredAt`      | Time since the durable agent execution holding the fence settled. Fences of running executions (`NULL`) are never pruned         |
+| `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives                                                                              |
+| `observability`   | `spans`            | `startedAt`      | Span age                                                                                                                         |
+| `observability`   | `metrics`          | `timestamp`      | Metric event age (vNext only)                                                                                                    |
+| `observability`   | `logs`             | `timestamp`      | Log event age (vNext only)                                                                                                       |
+| `observability`   | `scores`           | `timestamp`      | Score event age (vNext only)                                                                                                     |
+| `observability`   | `feedback`         | `timestamp`      | Feedback event age (vNext only)                                                                                                  |
+| `scores`          | `scorers`          | `createdAt`      | Score record age                                                                                                                 |
+| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive                                                                          |
+| `workflows`       | `runOwnership`     | `updatedAt`      | Inactivity. A running durable agent execution renews its claim every 10 seconds, so keep `maxAge` well above its 30-second lease |
+| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned                                                                 |
+| `experiments`     | `experiments`      | `completedAt`    | Time since completion, running experiments are never pruned                                                                      |
+| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                                                                                 |
+| `harness`         | `sessions`         | `createdAt`      | Session record age                                                                                                               |
+| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                                                                                               |
 
 > **Note:**
 >
 > - The memory `observational_memory` table has no timestamp anchor, so it can't be age-pruned and isn't a valid retention key.
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
+> - `runOwnership` and `runFences` hold the run fencing records of durable agents, one small record per run in each. If the `runOwnership` `maxAge` is too short, a running execution can lose its run, but an execution that lost a run still can't write. A fence is retired only when its execution settles, so the fence of a run that crashed and was never recovered is never pruned.
 > - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
 > - DuckDB observability stores append-only events for all five signals. Its `spans` policy uses the event `timestamp` column rather than `startedAt`.

package/dist/index.cjs

@@ -360,6 +360,7 @@ function resolveClickhouseConfig(config) {
 			username: config.username,
 			password: config.password,
 			clickhouse_settings: {
+				...config.clickhouse_settings,
 				date_time_input_format: "best_effort",
 				date_time_output_format: "iso",
 				use_client_time_zone: 1,
@@ -7106,18 +7107,14 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters,
 	const to = parameters.add(selection.timeRange.to, "DateTime64(3, 'UTC')");
 	const tenant = compileTenantScope(scope, parameters);
 	const ctes = [`current_roots AS (
-    SELECT * FROM (
-      SELECT *
-      FROM ${TABLE_TRACE_ROOTS}
-      WHERE traceId IN (
-        SELECT traceId
-        FROM ${TABLE_TRACE_ROOTS} r
-        WHERE startedAt >= ${from}
-          AND startedAt < ${to}${tenant}${seedConjuncts.map((conjunct) => `\n          AND (${compilePredicate(conjunct, parameters)})`).join("")}
-      )
-      ORDER BY dedupeKey
-      LIMIT 1 BY dedupeKey
-    )
+    SELECT *
+    FROM ${TABLE_TRACE_ROOTS}
+    WHERE traceId IN (
+      SELECT traceId
+      FROM ${TABLE_TRACE_ROOTS} r
+      WHERE startedAt >= ${from}
+        AND startedAt < ${to}${tenant}${seedConjuncts.map((conjunct) => `\n          AND (${compilePredicate(conjunct, parameters)})`).join("")}
+    )${tenant}
     ORDER BY traceId, dedupeKey
     LIMIT 1 BY traceId
   )`, `root_scope AS (