@mastra/clickhouse 1.5.2 → 1.6.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @mastra/clickhouse
 
+## 1.6.0-alpha.0
+
+### Minor Changes
+
+- Added ClickhouseStoreVNext, a ClickHouse storage adapter that uses the vNext observability domain by default. Equivalent to constructing a ClickhouseStore and overriding the observability domain manually, but exposed as a single class for new projects. ([#15984](https://github.com/mastra-ai/mastra/pull/15984))
+
+  ```typescript
+  import { Mastra } from '@mastra/core';
+  import { ClickhouseStoreVNext } from '@mastra/clickhouse';
+
+  export const mastra = new Mastra({
+    storage: new ClickhouseStoreVNext({
+      id: 'clickhouse-storage',
+      url: process.env.CLICKHOUSE_URL!,
+      username: process.env.CLICKHOUSE_USERNAME!,
+      password: process.env.CLICKHOUSE_PASSWORD!,
+    }),
+  });
+  ```
+
+  ClickhouseStoreVNext accepts the same configuration as ClickhouseStore and reuses the same ClickHouse client across every domain. ClickhouseStore continues to work for projects on the legacy observability schema.
+
+### Patch Changes
+
+- Updated dependencies [[`1723e09`](https://github.com/mastra-ai/mastra/commit/1723e099829892419ddbfe49287acfeac2522724), [`629f9e9`](https://github.com/mastra-ai/mastra/commit/629f9e9a7e56aa8f129515a3923c5813298790c7), [`25168fb`](https://github.com/mastra-ai/mastra/commit/25168fb9c1de9db7f8171df4f58ceb842c53aa29), [`ab34b5a`](https://github.com/mastra-ai/mastra/commit/ab34b5a2191b8e4353df1dbf7b9155e7d6628d79), [`5fb6c2a`](https://github.com/mastra-ai/mastra/commit/5fb6c2a95c1843cc231704b91354311fc1f34a71), [`394f0cf`](https://github.com/mastra-ai/mastra/commit/394f0cfc31e6b4d801219fdef2e9cc69e5bc8682), [`3d7f709`](https://github.com/mastra-ai/mastra/commit/3d7f709b615e588050bb6283c4ee5cfe2978cbde), [`48a42f1`](https://github.com/mastra-ai/mastra/commit/48a42f114a4006a95e0b7a1b5ad1a24815a175c2), [`2c83efc`](https://github.com/mastra-ai/mastra/commit/2c83efc4482b3efe50830e3b8b4ba9a8d219edff), [`282a10c`](https://github.com/mastra-ai/mastra/commit/282a10c9446e9922afe80e10e3770481c8ac8a28)]:
+  - @mastra/core@1.31.0-alpha.0
+
 ## 1.5.2
 
 ### Patch Changes

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.5.2"
+  version: "1.6.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -2,15 +2,13 @@
 
 [ClickHouse](https://clickhouse.com/) is a columnar database designed for analytical workloads. The `@mastra/clickhouse` package provides storage adapters for several Mastra storage domains and is the recommended backend for production observability.
 
-ClickHouse is most commonly used as the dedicated observability backend in a [composite storage](https://mastra.ai/reference/storage/composite) setup, with another database serving the remaining domains. It can also back the supported domains on its own through `ClickhouseStore`.
+ClickHouse is most commonly used as the dedicated observability backend in a [composite storage](https://mastra.ai/reference/storage/composite) setup, with another database serving the remaining domains.
 
 ## When to use ClickHouse
 
-- Production observability for traces, logs, metrics, scores, and feedback.
-- Append-heavy workloads where columnar storage and compression help keep costs down.
-- Deployment platforms with ephemeral filesystems (such as [Railway](#deploying-with-railway-and-similar-platforms), Fly.io, Render, Heroku, or container schedulers) where embedded backends like DuckDB cannot persist data.
+Production observability for traces, logs, metrics, scores, and feedback.
 
-For local development, [LibSQL](https://mastra.ai/reference/storage/libsql) or `@mastra/duckdb` are usually a better fit because they need no external service.
+For local development, use a composite store that combines [LibSQL](https://mastra.ai/reference/storage/libsql) (for memory and workflows) and `@mastra/duckdb` (for observability). Neither alone covers a development setup: LibSQL does not implement the observability domain, and DuckDB does not implement the other domains. See the [observability overview](https://mastra.ai/docs/observability/overview) for an example.
 
 ## Installation
 
@@ -51,7 +49,7 @@ Compose it with another storage adapter so observability writes do not contend w
 ```typescript
 import { Mastra } from '@mastra/core'
 import { MastraCompositeStore } from '@mastra/core/storage'
-import { LibSQLStore } from '@mastra/libsql'
+import { PostgresStore } from '@mastra/pg'
 import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
 import { Observability, DefaultExporter } from '@mastra/observability'
 
@@ -64,9 +62,9 @@ const observabilityStore = new ObservabilityStorageClickhouseVNext({
 export const mastra = new Mastra({
   storage: new MastraCompositeStore({
     id: 'composite-storage',
-    default: new LibSQLStore({
-      id: 'mastra-storage',
-      url: 'file:./mastra.db',
+    default: new PostgresStore({
+      id: 'pg',
+      connectionString: process.env.DATABASE_URL!,
     }),
     domains: {
       observability: observabilityStore,
@@ -101,16 +99,16 @@ const observabilityStore = new ObservabilityStorageClickhouse({
 
 New projects should use `ObservabilityStorageClickhouseVNext` instead.
 
-### Full storage with `ClickhouseStore`
+### ClickHouse for every domain
 
-`ClickhouseStore` implements the `memory`, `workflows`, `scores`, and `observability` domains. Use it when you want a single backend for the supported domains. For most observability deployments, the composite setup above is preferable because it isolates observability writes from primary application data.
+`ClickhouseStoreVNext` backs the `memory`, `workflows`, and `observability` domains with ClickHouse and uses the vNext observability adapter automatically. Use it when you want ClickHouse to back the entire application without wiring a composite store manually.
 
 ```typescript
 import { Mastra } from '@mastra/core'
-import { ClickhouseStore } from '@mastra/clickhouse'
+import { ClickhouseStoreVNext } from '@mastra/clickhouse'
 
 export const mastra = new Mastra({
-  storage: new ClickhouseStore({
+  storage: new ClickhouseStoreVNext({
     id: 'clickhouse-storage',
     url: process.env.CLICKHOUSE_URL!,
     username: process.env.CLICKHOUSE_USERNAME!,
@@ -119,6 +117,34 @@ export const mastra = new Mastra({
 })
 ```
 
+`ClickhouseStoreVNext` accepts the same configuration as `ClickhouseStore` and reuses the same ClickHouse client across every domain.
+
+#### Manual composition
+
+`ClickhouseStore` is the long-standing class that backs every domain with the legacy observability adapter. New projects should prefer `ClickhouseStoreVNext`. If you need to customize the composite (for example, to override one domain with a different backend), build it manually:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { ClickhouseStore, ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
+
+const credentials = {
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+}
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite-storage',
+    default: new ClickhouseStore({ id: 'clickhouse-storage', ...credentials }),
+    domains: {
+      observability: new ObservabilityStorageClickhouseVNext(credentials),
+    },
+  }),
+})
+```
+
 ### Bring your own ClickHouse client
 
 Pass a pre-configured client when you need custom connection settings such as request timeouts, compression, or interceptors:
@@ -150,7 +176,7 @@ The same `client` form is accepted by `ObservabilityStorageClickhouse` and `Obse
 
 **username** (`string`): ClickHouse username. Required when not passing a pre-configured \`client\`.
 
-**password** (`string`): ClickHouse password. Required when not passing a pre-configured \`client\`. Can be an empty string for the default user on a local instance.
+**password** (`string`): ClickHouse password. Required when not passing a pre-configured \`client\`. It can be an empty string for the default user on a local instance.
 
 **client** (`ClickHouseClient`): Pre-configured ClickHouse client from \`@clickhouse/client\`. Use this when you need custom request settings. Mutually exclusive with the credential fields above.
 

package/dist/index.cjs

@@ -7152,10 +7152,22 @@ var ClickhouseStore = class extends storage.MastraCompositeStore {
     }
   }
 };
+var ClickhouseStoreVNext = class extends ClickhouseStore {
+  constructor(config) {
+    super(config);
+    this.name = "ClickhouseStoreVNext";
+    const observability = new ObservabilityStorageClickhouseVNext({ client: this.db });
+    this.stores = {
+      ...this.stores,
+      observability
+    };
+  }
+};
 
 exports.BackgroundTasksStorageClickhouse = BackgroundTasksStorageClickhouse;
 exports.COLUMN_TYPES = COLUMN_TYPES;
 exports.ClickhouseStore = ClickhouseStore;
+exports.ClickhouseStoreVNext = ClickhouseStoreVNext;
 exports.MemoryStorageClickhouse = MemoryStorageClickhouse;
 exports.ObservabilityStorageClickhouse = ObservabilityStorageClickhouse;
 exports.ObservabilityStorageClickhouseVNext = ObservabilityStorageClickhouseVNext;