@mastra/clickhouse 1.11.1-alpha.0 → 1.12.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @mastra/clickhouse
 
+## 1.12.0-alpha.0
+
+### Minor Changes
+
+- Added legacy-to-VNext span migration for ClickHouse observability storage. Customers using `ObservabilityStorageClickhouse` (legacy) can now run `npx mastra migrate` to copy historical spans from `mastra_ai_spans` to the VNext `mastra_span_events` schema. The migration handles column mapping, batches by day for memory safety, deduplicates legacy rows, converts empty-string parentSpanId to NULL for correct root span detection, and supports both old (`Nullable(String)` JSON) and new (`Array(String)`) tags schemas. The legacy table is preserved as a backup after migration. ([#19050](https://github.com/mastra-ai/mastra/pull/19050))
+
+### Patch Changes
+
+- Updated dependencies [[`e955965`](https://github.com/mastra-ai/mastra/commit/e955965dce575a903e37cf054d28ea99aa48785e), [`860ef7e`](https://github.com/mastra-ai/mastra/commit/860ef7e77d92b63469cbe5857aa1e626197e43e9), [`17e818c`](https://github.com/mastra-ai/mastra/commit/17e818c51a958ba90641b1a959dc38faf8c034e9), [`4451dfe`](https://github.com/mastra-ai/mastra/commit/4451dfe857428e7abcc0261a507a2e186dae6d47), [`1d39058`](https://github.com/mastra-ai/mastra/commit/1d39058e548efd691799985d5c8af2737f1c3bd2)]:
+  - @mastra/core@1.51.0-alpha.2
+
+## 1.11.1
+
+### Patch Changes
+
+- Added optional `organizationId` and `projectId` fields to scores for multi-tenant isolation. Scores can now be saved with tenancy metadata and the `listScoresBy*` methods accept a `filters` option to scope results by organization and project. ([#18331](https://github.com/mastra-ai/mastra/pull/18331))
+
+  ```ts
+  await storage.saveScore({ ...score, organizationId: 'org-a', projectId: 'proj-1' });
+
+  const result = await storage.listScoresByScorerId({
+    scorerId,
+    filters: { organizationId: 'org-a', projectId: 'proj-1' },
+  });
+  ```
+
+  `projectId` identifies the project scope, separate from `resourceId` which continues to mean the agent memory resource.
+
+- Updated dependencies [[`700619b`](https://github.com/mastra-ai/mastra/commit/700619b61d572e592cbaaf758121d168844ca4d2), [`0f69865`](https://github.com/mastra-ai/mastra/commit/0f69865aced225d98eac812e22699dc445ee18cb), [`9250acd`](https://github.com/mastra-ai/mastra/commit/9250acd1357f0f1f33d0dcca16f9655084c58eca), [`0c3d4bc`](https://github.com/mastra-ai/mastra/commit/0c3d4bcae13ea3699d379403e6f350d5cf4efe9f), [`cc440a3`](https://github.com/mastra-ai/mastra/commit/cc440a39400d8ce06655462b26c1666a1b3d4320), [`6a61846`](https://github.com/mastra-ai/mastra/commit/6a61846eeda29fb714549b70f1bee2bf6b141c44), [`215f9b0`](https://github.com/mastra-ai/mastra/commit/215f9b0f3f3f6fc165edad360582dd4d3d7ea748), [`17369b2`](https://github.com/mastra-ai/mastra/commit/17369b25250561e9ed994ae509be1d15bfb33bcb), [`c64c2a8`](https://github.com/mastra-ai/mastra/commit/c64c2a8503a50252f9ca6b8e8c54cadee31b92a2), [`bcae929`](https://github.com/mastra-ai/mastra/commit/bcae929945cbf265bd9f327cc715ecafa072b5b9), [`ea6327b`](https://github.com/mastra-ai/mastra/commit/ea6327ba2d63ca647804bc97b347e03a58617162), [`3439fa8`](https://github.com/mastra-ai/mastra/commit/3439fa836ecfcaa257b40c20b30ac2a8be22e9ea), [`85107f2`](https://github.com/mastra-ai/mastra/commit/85107f2758b527147fccbedff962961927c2d3b8), [`b33822e`](https://github.com/mastra-ai/mastra/commit/b33822e8d470884954b02f7b0745407ee4ef74b1), [`06e2680`](https://github.com/mastra-ai/mastra/commit/06e26806b51d2cbd858afdc66daa2b86ff3ba64a), [`06ff9e0`](https://github.com/mastra-ai/mastra/commit/06ff9e0befd1d642ab87ff749285ee4091205c7e), [`d5c11e3`](https://github.com/mastra-ai/mastra/commit/d5c11e3ba5045969caa7272a7bd1fd141c93ab6c), [`7f5e1ff`](https://github.com/mastra-ai/mastra/commit/7f5e1ff695a92f672bb3976363925d1e9136b54a), [`ff80671`](https://github.com/mastra-ai/mastra/commit/ff8067185e208b27198b4e5b71803013175c3643), [`b8375c1`](https://github.com/mastra-ai/mastra/commit/b8375c1f8fe905df8ae2ae9a893bb365f17aec4e), [`dab1257`](https://github.com/mastra-ai/mastra/commit/dab1257b64e4ed576dc5038bb7a3f7072338bc9f), [`1240f05`](https://github.com/mastra-ai/mastra/commit/1240f051c8e5371f1c014448bf37b1a1b9a05e47), [`705ff39`](https://github.com/mastra-ai/mastra/commit/705ff3969e57214ff2fdaf3815d751dd558886ed), [`e6fbd5b`](https://github.com/mastra-ai/mastra/commit/e6fbd5bfdc28e92c0c0433f29aa1bc152d3430f6), [`215f9b0`](https://github.com/mastra-ai/mastra/commit/215f9b0f3f3f6fc165edad360582dd4d3d7ea748), [`24c10d3`](https://github.com/mastra-ai/mastra/commit/24c10d333e6649ac06075903aeeee13a933db3b3), [`24c10d3`](https://github.com/mastra-ai/mastra/commit/24c10d333e6649ac06075903aeeee13a933db3b3), [`24c10d3`](https://github.com/mastra-ai/mastra/commit/24c10d333e6649ac06075903aeeee13a933db3b3), [`6f2026c`](https://github.com/mastra-ai/mastra/commit/6f2026cdf114ff1e21e49133ca774ec7d5085059), [`24c10d3`](https://github.com/mastra-ai/mastra/commit/24c10d333e6649ac06075903aeeee13a933db3b3), [`215f9b0`](https://github.com/mastra-ai/mastra/commit/215f9b0f3f3f6fc165edad360582dd4d3d7ea748), [`215f9b0`](https://github.com/mastra-ai/mastra/commit/215f9b0f3f3f6fc165edad360582dd4d3d7ea748), [`003f35d`](https://github.com/mastra-ai/mastra/commit/003f35d19e07b23b4bacc591c8bc0c59b42124ae), [`f890eda`](https://github.com/mastra-ai/mastra/commit/f890eda2c8a2ae83d9b30bc6d85842f93b6c266b), [`1340fb7`](https://github.com/mastra-ai/mastra/commit/1340fb76262a3ca062130aa71859f07257a0a5a4)]:
+  - @mastra/core@1.49.0
+
 ## 1.11.1-alpha.0
 
 ### 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.11.1-alpha.0"
+  version: "1.12.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -101,6 +101,38 @@ const observabilityStore = new ObservabilityStorageClickhouse({
 
 New projects should use `ObservabilityStorageClickhouseVNext` instead.
 
+### Migrating from legacy to vNext
+
+To migrate historical spans from the legacy `mastra_ai_spans` table to the vNext schema, run:
+
+**npm**:
+
+```bash
+npx mastra migrate
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra migrate
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra migrate
+```
+
+**Bun**:
+
+```bash
+bun x mastra migrate
+```
+
+The migration copies span data from `mastra_ai_spans` into `mastra_span_events` in day-sized batches. It handles column mapping, deduplicates legacy rows, and preserves the original table as a backup. After migration, traces appear in Studio through the vNext adapter.
+
+> **Note:** The legacy table is not deleted. Drop it manually after verifying the migration.
+
 ### ClickHouse for every domain
 
 `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.
@@ -174,19 +206,19 @@ The same `client` form is accepted by `ObservabilityStorageClickhouse` and `Obse
 
 **id** (`string`): Unique identifier for this storage instance.
 
-**url** (`string`): ClickHouse server URL (for example, \`https\://your-instance.clickhouse.cloud:8443\` or \`http\://localhost:8123\`). Required when not passing a pre-configured \`client\`.
+**url** (`string`): ClickHouse server URL (for example, https\://your-instance.clickhouse.cloud:8443 or http\://localhost:8123). Required when not passing a pre-configured client.
 
-**username** (`string`): ClickHouse username. Required when not passing a pre-configured \`client\`.
+**username** (`string`): ClickHouse username. Required when not passing a pre-configured client.
 
-**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.
+**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.
+**client** (`ClickHouseClient`): Pre-configured ClickHouse client from @clickhouse/client. Use this when you need custom request settings. Mutually exclusive with the credential fields above.
 
-**ttl** (`object`): Per-table TTL configuration applied at table creation time. Accepts row-level and column-level TTLs in interval units from \`NANOSECOND\` through \`YEAR\`.
+**ttl** (`object`): Per-table TTL configuration applied at table creation time. Accepts row-level and column-level TTLs in interval units from NANOSECOND through YEAR.
 
-**replication** (`{ cluster?: string; zookeeperPath?: string; replicaName?: string }`): Opt-in replicated table configuration for multi-replica ClickHouse clusters. When set, Mastra creates replicated MergeTree tables. When \`cluster\` is set, Mastra also adds \`ON CLUSTER\` to Mastra-owned data definition language (DDL).
+**replication** (`{ cluster?: string; zookeeperPath?: string; replicaName?: string }`): Opt-in replicated table configuration for multi-replica ClickHouse clusters. When set, Mastra creates replicated MergeTree tables. When cluster is set, Mastra also adds ON CLUSTER to Mastra-owned data definition language (DDL).
 
-**disableInit** (`boolean`): When \`true\`, the store does not run table creation or migrations on first use. Call \`storage.init()\` explicitly from your deployment scripts. (Default: `false`)
+**disableInit** (`boolean`): When true, the store does not run table creation or migrations on first use. Call storage.init() explicitly from your deployment scripts. (Default: `false`)
 
 `ClickhouseStore` also accepts every option from `ClickHouseClientConfigOptions` (such as `database`, `request_timeout`, `compression`, `keep_alive`, and `max_open_connections`).
 
@@ -211,7 +243,7 @@ When `replication` is set, Mastra rewrites its `MergeTree` and `ReplacingMergeTr
 - `zookeeperPath`: `'/clickhouse/tables/{shard}/{database}/{table}'`
 - `replicaName`: `'{replica}'`
 
-The defaults match the most common self-managed convention. If your cluster's existing tables use a different layout (for example `/clickhouse/tables/{shard}/{table}` without the `{database}` segment), set `zookeeperPath` explicitly to match. Mastra does not read your cluster's convention from Keeper, so a mismatched default writes Mastra's metadata to a separate branch from the rest of the cluster.
+The defaults match the most common self-managed convention. If your cluster's existing tables use a different layout (for example `/clickhouse/tables/{shard}/{table}` without the `{database}` segment), set `zookeeperPath` explicitly to match. Mastra doesn't read your cluster's convention from Keeper, so a mismatched default writes Mastra's metadata to a separate branch from the rest of the cluster.
 
 ```typescript
 new ClickhouseStoreVNext({
@@ -231,7 +263,7 @@ Manual maintenance such as `optimizeTable()` and `materializeTtl()` runs on ever
 
 If existing Mastra tables use local `MergeTree` or `ReplacingMergeTree` engines, initialization fails while `replication` is enabled. Mastra refuses to silently convert local tables because copy-and-swap is unsafe across replicas. To migrate, recreate the affected tables as `Replicated*` before enabling replication. The typical sequence is: rename the local table, run `CREATE TABLE ... ENGINE = ReplicatedMergeTree(...) ON CLUSTER ...`, run `INSERT INTO ... SELECT * FROM <renamed_local>`, then drop the renamed local table.
 
-Do not set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side, and explicit `ReplicatedMergeTree` engines produce incorrect DDL. `replication` is only for self-managed multi-replica clusters.
+Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side, and explicit `ReplicatedMergeTree` engines produce incorrect DDL. `replication` is only for self-managed multi-replica clusters.
 
 ### Observability domain options
 

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

@@ -37,25 +37,25 @@ You'll also need to install the storage providers you want to compose:
 **npm**:
 
 ```bash
-npm install @mastra/pg@latest @mastra/libsql@latest
+npm install @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 **pnpm**:
 
 ```bash
-pnpm add @mastra/pg@latest @mastra/libsql@latest
+pnpm add @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 **Yarn**:
 
 ```bash
-yarn add @mastra/pg@latest @mastra/libsql@latest
+yarn add @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 **Bun**:
 
 ```bash
-bun add @mastra/pg@latest @mastra/libsql@latest
+bun add @mastra/pg@latest @mastra/libsql@latest @mastra/mongodb@latest
 ```
 
 ## Storage domains
@@ -124,15 +124,73 @@ export const mastra = new Mastra({
 })
 ```
 
+### Mixed backends
+
+Use domain classes from each storage package to route different domains to different backends. The following example stores memory and workflow state in MongoDB, then routes observability to ClickHouse:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { ObservabilityStorageClickhouse } from '@mastra/clickhouse'
+import { MemoryStorageMongoDB, WorkflowsStorageMongoDB } from '@mastra/mongodb'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    domains: {
+      memory: new MemoryStorageMongoDB({
+        uri: process.env.MONGODB_URI,
+        dbName: 'mastra_memory',
+      }),
+      workflows: new WorkflowsStorageMongoDB({
+        uri: process.env.MONGODB_URI,
+        dbName: 'mastra_workflows',
+      }),
+      observability: new ObservabilityStorageClickhouse({
+        url: process.env.CLICKHOUSE_URL,
+        username: process.env.CLICKHOUSE_USERNAME,
+        password: process.env.CLICKHOUSE_PASSWORD,
+      }),
+    },
+  }),
+})
+```
+
+### Disabling a domain
+
+Set a domain to `false` to disable it. A disabled domain doesn't fall back to `default`, so data for that domain isn't persisted:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+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: {
+      // don't persist traces and spans
+      observability: false,
+    },
+  }),
+})
+```
+
 ## Options
 
 **id** (`string`): Unique identifier for this storage instance.
 
-**default** (`MastraCompositeStore`): Default storage adapter. Domains not explicitly specified in \`domains\` will use this storage's domains as fallbacks.
+**default** (`MastraCompositeStore`): Default storage adapter. Domains not explicitly specified in domains will use this storage's domains as fallbacks.
 
 **disableInit** (`boolean`): When true, automatic initialization is disabled. You must call init() explicitly.
 
-**domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both \`editor\` and \`default\` storage.
+**domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage. Set a domain to false to disable it entirely; a disabled domain does not fall back to editor or default.
 
 **domains.memory** (`MemoryStorage`): Storage for threads, messages, and resources.
 
@@ -274,6 +332,6 @@ const storage = new MastraCompositeStore({
 })
 ```
 
-Do not set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for the full config shape and operator notes.
+Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for the full config shape and operator notes.
 
 > **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for the full list of supported providers.

package/dist/index.cjs

@@ -5949,6 +5949,11 @@ async function getTableColumns(client, table) {
   const rows = await result.json();
   return rows.map((r) => r.name);
 }
+async function getTableColumnTypes(client, table) {
+  const result = await client.query({ query: `DESCRIBE TABLE ${table}`, format: "JSONEachRow" });
+  const rows = await result.json();
+  return new Map(rows.map((r) => [r.name, r.type]));
+}
 function buildTemporaryTableDDL(createDDL, table, tempTable) {
   return createDDL.replace(`CREATE TABLE IF NOT EXISTS ${table}`, `CREATE TABLE ${tempTable}`);
 }
@@ -5982,6 +5987,218 @@ async function checkSignalTablesMigrationStatus(client) {
     tables
   };
 }
+var TABLE_LEGACY_SPANS = "mastra_ai_spans";
+var PROMOTED_METADATA_KEYS = [
+  "experimentId",
+  "entityType",
+  "entityId",
+  "entityName",
+  "entityVersionId",
+  "parentEntityVersionId",
+  "rootEntityVersionId",
+  "userId",
+  "organizationId",
+  "resourceId",
+  "runId",
+  "sessionId",
+  "threadId",
+  "requestId",
+  "environment",
+  "executionSource",
+  "serviceName"
+];
+var TABLE_LEGACY_MIGRATION_DONE = "mastra_legacy_span_migration_done";
+async function hasMarkerRow(client) {
+  const engine = await getTableEngine(client, TABLE_LEGACY_MIGRATION_DONE);
+  if (!engine) return false;
+  const result = await client.query({
+    query: `SELECT count() as cnt FROM ${TABLE_LEGACY_MIGRATION_DONE}`,
+    format: "JSONEachRow"
+  });
+  const rows = await result.json();
+  return Number(rows[0]?.cnt ?? 0) > 0;
+}
+async function checkLegacySpanMigrationStatus(client) {
+  if (await hasMarkerRow(client)) {
+    return { needsMigration: false };
+  }
+  const engine = await getTableEngine(client, TABLE_LEGACY_SPANS);
+  if (!engine) {
+    return { needsMigration: false };
+  }
+  const countResult = await client.query({
+    query: `SELECT count() as cnt FROM ${TABLE_LEGACY_SPANS}`,
+    format: "JSONEachRow"
+  });
+  const countRows = await countResult.json();
+  const legacyRowCount = Number(countRows[0]?.cnt ?? 0);
+  if (legacyRowCount === 0) {
+    return { needsMigration: false };
+  }
+  return { needsMigration: true };
+}
+var VNEXT_SPAN_COLUMNS = [
+  "dedupeKey",
+  "traceId",
+  "spanId",
+  "parentSpanId",
+  "experimentId",
+  "entityType",
+  "entityId",
+  "entityName",
+  "entityVersionId",
+  "parentEntityVersionId",
+  "parentEntityType",
+  "parentEntityId",
+  "parentEntityName",
+  "rootEntityVersionId",
+  "rootEntityType",
+  "rootEntityId",
+  "rootEntityName",
+  "userId",
+  "organizationId",
+  "resourceId",
+  "runId",
+  "sessionId",
+  "threadId",
+  "requestId",
+  "environment",
+  "executionSource",
+  "serviceName",
+  "name",
+  "spanType",
+  "isEvent",
+  "startedAt",
+  "endedAt",
+  "tags",
+  "metadataSearch",
+  "attributes",
+  "scope",
+  "links",
+  "input",
+  "output",
+  "error",
+  "metadataRaw",
+  "requestContext"
+];
+function buildLegacySpanSelectExprs(legacyColumnTypes) {
+  const has = (col) => legacyColumnTypes.has(col);
+  const colOrNull = (legacy) => has(legacy) ? `"${legacy}"` : "NULL";
+  const promotedIn = PROMOTED_METADATA_KEYS.map((k) => `'${k}'`).join(", ");
+  const metadataSearchExpr = has("metadata") ? `CAST(arrayFilter(x -> x.1 NOT IN (${promotedIn}) AND trim(BOTH ' ' FROM x.2) != '', arrayMap(x -> (x.1, trim(BOTH ' ' FROM x.2)), JSONExtractKeysAndValues(COALESCE("metadata", '{}'), 'String'))), 'Map(String, String)')` : `CAST(map(), 'Map(String, String)')`;
+  let tagsExpr = "[]";
+  if (has("tags")) {
+    const tagsType = legacyColumnTypes.get("tags");
+    if (tagsType.includes("Array")) {
+      tagsExpr = `arrayFilter(x -> x != '', arrayDistinct(arrayMap(x -> trim(BOTH ' ' FROM x), "tags")))`;
+    } else {
+      tagsExpr = `arrayFilter(x -> x != '', arrayDistinct(arrayMap(x -> trim(BOTH ' ' FROM x), JSONExtract(COALESCE("tags", '[]'), 'Array(String)'))))`;
+    }
+  }
+  const exprs = {
+    dedupeKey: `concat("traceId", ':', "spanId")`,
+    traceId: `"traceId"`,
+    spanId: `"spanId"`,
+    // Legacy stores '' for root spans; VNext MV filters on IS NULL.
+    parentSpanId: has("parentSpanId") ? `nullIf("parentSpanId", '')` : "NULL",
+    experimentId: colOrNull("experimentId"),
+    entityType: colOrNull("entityType"),
+    entityId: colOrNull("entityId"),
+    entityName: colOrNull("entityName"),
+    entityVersionId: colOrNull("entityVersionId"),
+    parentEntityVersionId: colOrNull("parentEntityVersionId"),
+    parentEntityType: colOrNull("parentEntityType"),
+    parentEntityId: colOrNull("parentEntityId"),
+    parentEntityName: colOrNull("parentEntityName"),
+    rootEntityVersionId: colOrNull("rootEntityVersionId"),
+    rootEntityType: colOrNull("rootEntityType"),
+    rootEntityId: colOrNull("rootEntityId"),
+    rootEntityName: colOrNull("rootEntityName"),
+    userId: colOrNull("userId"),
+    organizationId: colOrNull("organizationId"),
+    resourceId: colOrNull("resourceId"),
+    runId: colOrNull("runId"),
+    sessionId: colOrNull("sessionId"),
+    threadId: colOrNull("threadId"),
+    requestId: colOrNull("requestId"),
+    environment: colOrNull("environment"),
+    executionSource: has("source") ? `"source"` : "NULL",
+    serviceName: colOrNull("serviceName"),
+    name: `"name"`,
+    spanType: `"spanType"`,
+    isEvent: `"isEvent"`,
+    startedAt: `"startedAt"`,
+    // VNext requires non-null endedAt; events always use startedAt.
+    endedAt: `if("isEvent", "startedAt", COALESCE("endedAt", "startedAt"))`,
+    tags: tagsExpr,
+    metadataSearch: metadataSearchExpr,
+    attributes: colOrNull("attributes"),
+    scope: colOrNull("scope"),
+    links: colOrNull("links"),
+    input: colOrNull("input"),
+    output: colOrNull("output"),
+    error: colOrNull("error"),
+    metadataRaw: has("metadata") ? `"metadata"` : "NULL",
+    requestContext: colOrNull("requestContext")
+  };
+  return VNEXT_SPAN_COLUMNS.map((c) => `${exprs[c]} AS "${c}"`).join(",\n    ");
+}
+async function migrateLegacySpans(client, logger) {
+  if (await hasMarkerRow(client)) {
+    return { migratedRows: 0, batches: 0 };
+  }
+  const engine = await getTableEngine(client, TABLE_LEGACY_SPANS);
+  if (!engine) {
+    return { migratedRows: 0, batches: 0 };
+  }
+  const legacyColumnTypes = await getTableColumnTypes(client, TABLE_LEGACY_SPANS);
+  const hasUpdatedAt = legacyColumnTypes.has("updatedAt");
+  await client.command({ query: SPAN_EVENTS_DDL });
+  await client.command({ query: TRACE_ROOTS_DDL });
+  await client.command({ query: TRACE_BRANCHES_DDL });
+  await client.command({ query: TRACE_ROOTS_MV_DDL });
+  await client.command({ query: TRACE_BRANCHES_MV_DDL });
+  const selectExprs = buildLegacySpanSelectExprs(legacyColumnTypes);
+  const columnList = VNEXT_SPAN_COLUMNS.map((c) => `"${c}"`).join(", ");
+  const dedupOrder = hasUpdatedAt ? `ORDER BY "traceId", "spanId", COALESCE("updatedAt", "createdAt") DESC` : `ORDER BY "traceId", "spanId", "createdAt" DESC`;
+  const daysResult = await client.query({
+    query: `SELECT
+      toString(toDate(COALESCE(endedAt, startedAt))) as day,
+      count() as cnt
+    FROM ${TABLE_LEGACY_SPANS}
+    GROUP BY day
+    ORDER BY day`,
+    format: "JSONEachRow"
+  });
+  const days = await daysResult.json();
+  let migratedRows = 0;
+  let batches = 0;
+  for (const { day, cnt } of days) {
+    const dayCount = Number(cnt);
+    await client.command({
+      query: `INSERT INTO ${TABLE_SPAN_EVENTS} (${columnList})
+        SELECT ${selectExprs}
+        FROM ${TABLE_LEGACY_SPANS}
+        WHERE toDate(COALESCE(endedAt, startedAt)) = {batchDate:Date}
+        ${dedupOrder}
+        LIMIT 1 BY "traceId", "spanId"`,
+      query_params: { batchDate: day }
+    });
+    migratedRows += dayCount;
+    batches++;
+    logger?.info?.(`Migrated batch ${day}: ${dayCount} rows`);
+  }
+  await client.command({
+    query: `CREATE TABLE IF NOT EXISTS ${TABLE_LEGACY_MIGRATION_DONE} (completedAt DateTime64(3, 'UTC')) ENGINE = MergeTree ORDER BY completedAt`
+  });
+  await client.command({
+    query: `INSERT INTO ${TABLE_LEGACY_MIGRATION_DONE} VALUES (now64(3))`
+  });
+  logger?.info?.(
+    `Legacy span migration complete: ${migratedRows} rows in ${batches} batches. The legacy table '${TABLE_LEGACY_SPANS}' has been preserved. Drop it manually after verifying the migration.`
+  );
+  return { migratedRows, batches };
+}
 async function migrateSignalTables(client, logger) {
   for (const { table, createDDL, idColumn } of SIGNAL_MIGRATIONS) {
     const engine = await getTableEngine(client, table);
@@ -7296,6 +7513,15 @@ var ObservabilityStorageClickhouseVNext = class extends storage.ObservabilitySto
         })
       });
     }
+    try {
+      const legacyStatus = await checkLegacySpanMigrationStatus(this.#client);
+      if (legacyStatus.needsMigration) {
+        this.logger?.warn?.(
+          `Legacy span table 'mastra_ai_spans' detected. Run 'npx mastra migrate' to migrate historical spans to the v-next schema.`
+        );
+      }
+    } catch {
+    }
     try {
       await assertExistingTablesCompatibleWithReplication(this.#client, this.#replication);
       const existingStrategy = await detectExistingDeltaCursorStrategy(this.#client);
@@ -7370,34 +7596,44 @@ var ObservabilityStorageClickhouseVNext = class extends storage.ObservabilitySto
     }
   }
   /**
-   * Manually migrate legacy signal tables to the signal-ID ReplacingMergeTree schema.
-   * The public method name is historical; the CLI still calls `migrateSpans()`
-   * for observability migrations even though this now also migrates signal tables.
+   * Manually migrate legacy tables to the v-next schema.
+   * Handles both signal table migrations (MergeTree → ReplacingMergeTree)
+   * and legacy span migration (mastra_ai_spans → mastra_span_events).
    */
   async migrateSpans() {
-    const migrationStatus = await checkSignalTablesMigrationStatus(this.#client);
-    if (!migrationStatus.needsMigration) {
-      return {
-        success: true,
-        alreadyMigrated: true,
-        duplicatesRemoved: 0,
-        message: "Migration already complete. Signal tables already use signal-ID dedupe keys."
-      };
+    const messages = [];
+    const signalStatus = await checkSignalTablesMigrationStatus(this.#client);
+    if (signalStatus.needsMigration) {
+      if (isReplicationConfigured(this.#replication)) {
+        throw new error.MastraError({
+          id: storage.createStorageErrorId("CLICKHOUSE", "REPLICATION", "SIGNAL_TABLES_MIGRATION_UNSUPPORTED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.USER,
+          text: "ClickHouse replication is enabled, so Mastra will not run copy-and-swap signal table migrations automatically. Migrate existing local signal tables manually before enabling replication."
+        });
+      }
+      await migrateSignalTables(this.#client, this.logger);
+      messages.push(`Migrated signal tables: ${signalStatus.tables.map((t) => t.table).join(", ")}.`);
     }
-    if (isReplicationConfigured(this.#replication)) {
-      throw new error.MastraError({
-        id: storage.createStorageErrorId("CLICKHOUSE", "REPLICATION", "SIGNAL_TABLES_MIGRATION_UNSUPPORTED"),
-        domain: error.ErrorDomain.STORAGE,
-        category: error.ErrorCategory.USER,
-        text: "ClickHouse replication is enabled, so Mastra will not run copy-and-swap signal table migrations automatically. Migrate existing local signal tables manually before enabling replication."
-      });
+    const legacyStatus = await checkLegacySpanMigrationStatus(this.#client);
+    if (legacyStatus.needsMigration) {
+      if (isReplicationConfigured(this.#replication)) {
+        throw new error.MastraError({
+          id: storage.createStorageErrorId("CLICKHOUSE", "REPLICATION", "LEGACY_SPAN_MIGRATION_UNSUPPORTED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.USER,
+          text: "ClickHouse replication is enabled. Migrate legacy mastra_ai_spans manually before enabling replication."
+        });
+      }
+      const result = await migrateLegacySpans(this.#client, this.logger);
+      messages.push(`Migrated ${result.migratedRows} legacy spans in ${result.batches} batches.`);
     }
-    await migrateSignalTables(this.#client, this.logger);
+    const alreadyMigrated = !signalStatus.needsMigration && !legacyStatus.needsMigration;
     return {
       success: true,
-      alreadyMigrated: false,
+      alreadyMigrated,
       duplicatesRemoved: 0,
-      message: `Migration complete. Migrated signal tables: ${migrationStatus.tables.map((t) => t.table).join(", ")}.`
+      message: alreadyMigrated ? "Migration already complete." : `Migration complete. ${messages.join(" ")}`
     };
   }
   // -------------------------------------------------------------------------