@mastra/mcp-docs-server 1.0.0-beta.25 → 1.0.0-beta.26

package/.docs/organized/changelogs/%40mastra%2Fpg.md

@@ -1,5 +1,63 @@
 # @mastra/pg
 
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Fixed duplicate spans migration issue across all storage backends. When upgrading from older versions, existing duplicate (traceId, spanId) combinations in the spans table could prevent the unique constraint from being created. The migration deduplicates spans before adding the constraint. ([#12073](https://github.com/mastra-ai/mastra/pull/12073))
+
+  **Deduplication rules (in priority order):**
+  1. Keep completed spans (those with `endedAt` set) over incomplete spans
+  2. Among spans with the same completion status, keep the one with the newest `updatedAt`
+  3. Use `createdAt` as the final tiebreaker
+
+  **What changed:**
+  - Added `migrateSpans()` method to observability stores for manual migration
+  - Added `checkSpansMigrationStatus()` method to check if migration is needed
+  - All stores use optimized single-query deduplication to avoid memory issues on large tables
+
+  **Usage example:**
+
+  ```typescript
+  const observability = await storage.getStore('observability');
+  const status = await observability.checkSpansMigrationStatus();
+  if (status.needsMigration) {
+    const result = await observability.migrateSpans();
+    console.log(`Migration complete: ${result.duplicatesRemoved} duplicates removed`);
+  }
+  ```
+
+  Fixes #11840
+
+- Renamed MastraStorage to MastraCompositeStore for better clarity. The old MastraStorage name remains available as a deprecated alias for backward compatibility, but will be removed in a future version. ([#12093](https://github.com/mastra-ai/mastra/pull/12093))
+
+  **Migration:**
+
+  Update your imports and usage:
+
+  ```typescript
+  // Before
+  import { MastraStorage } from '@mastra/core/storage';
+
+  const storage = new MastraStorage({
+    id: 'composite',
+    domains: { ... }
+  });
+
+  // After
+  import { MastraCompositeStore } from '@mastra/core/storage';
+
+  const storage = new MastraCompositeStore({
+    id: 'composite',
+    domains: { ... }
+  });
+  ```
+
+  The new name better reflects that this is a composite storage implementation that routes different domains (workflows, traces, messages) to different underlying stores, avoiding confusion with the general "Mastra Storage" concept.
+
+- Updated dependencies [[`026b848`](https://github.com/mastra-ai/mastra/commit/026b8483fbf5b6d977be8f7e6aac8d15c75558ac), [`ffa553a`](https://github.com/mastra-ai/mastra/commit/ffa553a3edc1bd17d73669fba66d6b6f4ac10897)]:
+  - @mastra/core@1.0.0-beta.26
+
 ## 1.0.0-beta.14
 
 ### Patch Changes
@@ -440,63 +498,5 @@
   await workflows?.persistWorkflowSnapshot({ workflowName, runId, snapshot });
 
   const observability = await storage.getStore('observability');
-  await observability?.createSpan(span);
-  ```
-
-  ### Available Domains
-  - **`memory`**: Thread and message operations (`getThreadById`, `saveThread`, `saveMessages`, etc.)
-  - **`workflows`**: Workflow state persistence (`persistWorkflowSnapshot`, `loadWorkflowSnapshot`, `getWorkflowRunById`, etc.)
-  - **`scores`**: Evaluation scores (`saveScore`, `listScoresByScorerId`, etc.)
-  - **`observability`**: Tracing and spans (`createSpan`, `updateSpan`, `getTrace`, etc.)
-  - **`agents`**: Stored agent configurations (`createAgent`, `getAgentById`, `listAgents`, etc.)
-
-  ### Breaking Changes
-  - Passthrough methods have been removed from `MastraStorage` base class
-  - All storage adapters now require accessing domains via `getStore()`
-  - The `stores` property on storage instances is now the canonical way to access domain storage
-
-  ### Internal Changes
-  - Each storage adapter now initializes domain-specific stores in its constructor
-  - Domain stores share database connections and handle their own table initialization
-
-- Unified observability schema with entity-based span identification ([#11132](https://github.com/mastra-ai/mastra/pull/11132))
-
-  ## What changed
-
-  Spans now use a unified identification model with `entityId`, `entityType`, and `entityName` instead of separate `agentId`, `toolId`, `workflowId` fields.
-
-  **Before:**
-
-  ```typescript
-  // Old span structure
-  span.agentId; // 'my-agent'
-  span.toolId; // undefined
-  span.workflowId; // undefined
-  ```
-
-  **After:**
-
-  ```typescript
-  // New span structure
-  span.entityType; // EntityType.AGENT
-  span.entityId; // 'my-agent'
-  span.entityName; // 'My Agent'
-  ```
-
-  ## New `listTraces()` API
-
-  Query traces with filtering, pagination, and sorting:
-
-  ```typescript
-  const { spans, pagination } = await storage.listTraces({
-    filters: {
-      entityType: EntityType.AGENT,
-      entityId: 'my-agent',
-      userId: 'user-123',
-      environment: 'production',
-      status: TraceStatus.SUCCESS,
-      startedAt: { start: new Date('2024-01-01'), end: new Date('2024-01-31') },
-    },
-    pagination: { page: 0, perPage: 50 },
 
-... 3421 more lines hidden. See full changelog in package directory.
+... 3479 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md

@@ -1,5 +1,17 @@
 # @mastra/playground-ui
 
+## 7.0.0-beta.26
+
+### Patch Changes
+
+- Fixed scorer eligibility check in observability to also check span.entityType field ([#12078](https://github.com/mastra-ai/mastra/pull/12078))
+
+- Updated dependencies [[`026b848`](https://github.com/mastra-ai/mastra/commit/026b8483fbf5b6d977be8f7e6aac8d15c75558ac), [`ffa553a`](https://github.com/mastra-ai/mastra/commit/ffa553a3edc1bd17d73669fba66d6b6f4ac10897)]:
+  - @mastra/client-js@1.0.0-beta.26
+  - @mastra/core@1.0.0-beta.26
+  - @mastra/react@0.1.0-beta.26
+  - @mastra/ai-sdk@1.0.0-beta.16
+
 ## 7.0.0-beta.25
 
 ### Patch Changes
@@ -487,16 +499,4 @@
   - @mastra/client-js@1.0.0-beta.14
   - @mastra/react@0.1.0-beta.14
 
-## 7.0.0-beta.13
-
-### Patch Changes
-
-- Updated dependencies [[`919a22b`](https://github.com/mastra-ai/mastra/commit/919a22b25876f9ed5891efe5facbe682c30ff497)]:
-  - @mastra/core@1.0.0-beta.13
-  - @mastra/client-js@1.0.0-beta.13
-  - @mastra/react@0.1.0-beta.13
-
-## 7.0.0-beta.12
-
-
-... 4777 more lines hidden. See full changelog in package directory.
+... 4789 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/%40mastra%2Freact.md

@@ -1,6 +1,13 @@
-# @mastra/react-hooks
+# @mastra/react
 
-## 1.0.0-beta.25
+## 0.1.0-beta.26
+
+### Patch Changes
+
+- Updated dependencies [[`026b848`](https://github.com/mastra-ai/mastra/commit/026b8483fbf5b6d977be8f7e6aac8d15c75558ac)]:
+  - @mastra/client-js@1.0.0-beta.26
+
+## 0.1.0-beta.25
 
 ### Minor Changes
 
@@ -57,7 +64,7 @@
 - Updated dependencies [[`ed3e3dd`](https://github.com/mastra-ai/mastra/commit/ed3e3ddec69d564fe2b125e083437f76331f1283), [`47b1c16`](https://github.com/mastra-ai/mastra/commit/47b1c16a01c7ffb6765fe1e499b49092f8b7eba3), [`9312dcd`](https://github.com/mastra-ai/mastra/commit/9312dcd1c6f5b321929e7d382e763d95fdc030f5)]:
   - @mastra/client-js@1.0.0-beta.25
 
-## 1.0.0-beta.24
+## 0.1.0-beta.23
 
 ### Major Changes
 
@@ -491,12 +498,5 @@
 - Updated dependencies []:
   - @mastra/client-js@0.16.4
 
-## 0.0.10-alpha.0
-
-### Patch Changes
-
-- Updated dependencies []:
-  - @mastra/client-js@0.16.4-alpha.0
-
 
-... 286 more lines hidden. See full changelog in package directory.
+... 293 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/%40mastra%2Fserver.md

@@ -1,5 +1,14 @@
 # @mastra/server
 
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- Improve type handling with Zod ([#12091](https://github.com/mastra-ai/mastra/pull/12091))
+
+- Updated dependencies [[`026b848`](https://github.com/mastra-ai/mastra/commit/026b8483fbf5b6d977be8f7e6aac8d15c75558ac), [`ffa553a`](https://github.com/mastra-ai/mastra/commit/ffa553a3edc1bd17d73669fba66d6b6f4ac10897)]:
+  - @mastra/core@1.0.0-beta.26
+
 ## 1.0.0-beta.25
 
 ### Minor Changes
@@ -489,14 +498,5 @@
 
   **Automatic:** SQL-based stores (PostgreSQL, LibSQL, MSSQL) automatically add new columns to existing `spans` tables on initialization. Existing data is preserved with new columns set to `NULL`.
 
-  **No action required:** Your existing code continues to work. Adopt the new fields and `listTraces()` API at your convenience.
-
-### Patch Changes
-
-- Refactor storage architecture to use domain-specific stores via `getStore()` pattern ([#11361](https://github.com/mastra-ai/mastra/pull/11361))
-
-  ### Summary
-
-  This release introduces a new storage architecture that replaces passthrough methods on `MastraStorage` with domain-specific storage interfaces accessed via `getStore()`. This change reduces code duplication across storage adapters and provides a cleaner, more modular API.
 
-... 4961 more lines hidden. See full changelog in package directory.
+... 4970 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/%40mastra%2Fupstash.md

@@ -1,5 +1,38 @@
 # @mastra/upstash
 
+## 1.0.0-beta.13
+
+### Patch Changes
+
+- Renamed MastraStorage to MastraCompositeStore for better clarity. The old MastraStorage name remains available as a deprecated alias for backward compatibility, but will be removed in a future version. ([#12093](https://github.com/mastra-ai/mastra/pull/12093))
+
+  **Migration:**
+
+  Update your imports and usage:
+
+  ```typescript
+  // Before
+  import { MastraStorage } from '@mastra/core/storage';
+
+  const storage = new MastraStorage({
+    id: 'composite',
+    domains: { ... }
+  });
+
+  // After
+  import { MastraCompositeStore } from '@mastra/core/storage';
+
+  const storage = new MastraCompositeStore({
+    id: 'composite',
+    domains: { ... }
+  });
+  ```
+
+  The new name better reflects that this is a composite storage implementation that routes different domains (workflows, traces, messages) to different underlying stores, avoiding confusion with the general "Mastra Storage" concept.
+
+- Updated dependencies [[`026b848`](https://github.com/mastra-ai/mastra/commit/026b8483fbf5b6d977be8f7e6aac8d15c75558ac), [`ffa553a`](https://github.com/mastra-ai/mastra/commit/ffa553a3edc1bd17d73669fba66d6b6f4ac10897)]:
+  - @mastra/core@1.0.0-beta.26
+
 ## 1.0.0-beta.12
 
 ### Patch Changes
@@ -466,37 +499,4 @@
 
   **Type change:** `WorkflowState.error` and `WorkflowRunState.error` types changed from `string | Error` to `SerializedError`.
 
-  Other changes:
-  - Added `UpdateWorkflowStateOptions` type for workflow state updates
-
-- Updated dependencies [[`d5ed981`](https://github.com/mastra-ai/mastra/commit/d5ed981c8701c1b8a27a5f35a9a2f7d9244e695f), [`9650cce`](https://github.com/mastra-ai/mastra/commit/9650cce52a1d917ff9114653398e2a0f5c3ba808), [`932d63d`](https://github.com/mastra-ai/mastra/commit/932d63dd51be9c8bf1e00e3671fe65606c6fb9cd), [`b760b73`](https://github.com/mastra-ai/mastra/commit/b760b731aca7c8a3f041f61d57a7f125ae9cb215), [`695a621`](https://github.com/mastra-ai/mastra/commit/695a621528bdabeb87f83c2277cf2bb084c7f2b4), [`2b459f4`](https://github.com/mastra-ai/mastra/commit/2b459f466fd91688eeb2a44801dc23f7f8a887ab), [`486352b`](https://github.com/mastra-ai/mastra/commit/486352b66c746602b68a95839f830de14c7fb8c0), [`09e4bae`](https://github.com/mastra-ai/mastra/commit/09e4bae18dd5357d2ae078a4a95a2af32168ab08), [`24b76d8`](https://github.com/mastra-ai/mastra/commit/24b76d8e17656269c8ed09a0c038adb9cc2ae95a), [`243a823`](https://github.com/mastra-ai/mastra/commit/243a8239c5906f5c94e4f78b54676793f7510ae3), [`486352b`](https://github.com/mastra-ai/mastra/commit/486352b66c746602b68a95839f830de14c7fb8c0), [`c61fac3`](https://github.com/mastra-ai/mastra/commit/c61fac3add96f0dcce0208c07415279e2537eb62), [`6f14f70`](https://github.com/mastra-ai/mastra/commit/6f14f706ccaaf81b69544b6c1b75ab66a41e5317), [`09e4bae`](https://github.com/mastra-ai/mastra/commit/09e4bae18dd5357d2ae078a4a95a2af32168ab08), [`4524734`](https://github.com/mastra-ai/mastra/commit/45247343e384717a7c8404296275c56201d6470f), [`2a53598`](https://github.com/mastra-ai/mastra/commit/2a53598c6d8cfeb904a7fc74e57e526d751c8fa6), [`c7cd3c7`](https://github.com/mastra-ai/mastra/commit/c7cd3c7a187d7aaf79e2ca139de328bf609a14b4), [`847c212`](https://github.com/mastra-ai/mastra/commit/847c212caba7df0d6f2fc756b494ac3c75c3720d), [`6f941c4`](https://github.com/mastra-ai/mastra/commit/6f941c438ca5f578619788acc7608fc2e23bd176)]:
-  - @mastra/core@1.0.0-beta.12
-
-## 1.0.0-beta.6
-
-### Patch Changes
-
-- Add delete workflow run API ([#10991](https://github.com/mastra-ai/mastra/pull/10991))
-
-  ```typescript
-  await workflow.deleteWorkflowRunById(runId);
-  ```
-
-- Updated dependencies [[`edb07e4`](https://github.com/mastra-ai/mastra/commit/edb07e49283e0c28bd094a60e03439bf6ecf0221), [`b7e17d3`](https://github.com/mastra-ai/mastra/commit/b7e17d3f5390bb5a71efc112204413656fcdc18d), [`261473a`](https://github.com/mastra-ai/mastra/commit/261473ac637e633064a22076671e2e02b002214d), [`5d7000f`](https://github.com/mastra-ai/mastra/commit/5d7000f757cd65ea9dc5b05e662fd83dfd44e932), [`4f0331a`](https://github.com/mastra-ai/mastra/commit/4f0331a79bf6eb5ee598a5086e55de4b5a0ada03), [`8a000da`](https://github.com/mastra-ai/mastra/commit/8a000da0c09c679a2312f6b3aa05b2ca78ca7393)]:
-  - @mastra/core@1.0.0-beta.10
-
-## 1.0.0-beta.5
-
-### Patch Changes
-
-- Fix saveScore not persisting ID correctly, breaking getScoreById retrieval ([#10915](https://github.com/mastra-ai/mastra/pull/10915))
-
-  **What Changed**
-  - saveScore now correctly returns scores that can be retrieved with getScoreById
-  - Validation errors now include contextual information (scorer, entity, trace details) for easier debugging
-
-  **Impact**
-  Previously, calling getScoreById after saveScore would return null because the generated ID wasn't persisted to the database. This is now fixed across all store implementations, ensuring consistent behavior and data integrity.
-
-
-... 2783 more lines hidden. See full changelog in package directory.
+... 2816 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/create-mastra.md

@@ -1,5 +1,7 @@
 # create-mastra
 
+## 1.0.0-beta.18
+
 ## 1.0.0-beta.17
 
 ## 1.0.0-beta.16
@@ -496,7 +498,5 @@
 
 - Fix getting tool link path from agent in playground ui tools page ([#8135](https://github.com/mastra-ai/mastra/pull/8135))
 
-## 0.13.2-alpha.3
-
 
-... 1747 more lines hidden. See full changelog in package directory.
+... 1749 more lines hidden. See full changelog in package directory.

package/.docs/organized/changelogs/mastra.md

@@ -1,5 +1,29 @@
 # mastra
 
+## 1.0.0-beta.18
+
+### Minor Changes
+
+- Added `mastra migrate` CLI command to manually run storage migrations. This command bundles and executes the migration script against your configured storage backend, deduplicating spans and adding unique constraints. Useful when upgrading from older versions that may have duplicate (traceId, spanId) entries. ([#12073](https://github.com/mastra-ai/mastra/pull/12073))
+
+  **Usage:**
+
+  ```bash
+  npx mastra migrate
+  ```
+
+  **Options:**
+  - `-d, --dir <path>` - Path to your Mastra folder (default: `src/mastra`)
+  - `-r, --root <path>` - Path to your root folder
+  - `-e, --env <env>` - Custom env file to include
+  - `--debug` - Enable debug logs
+
+### Patch Changes
+
+- Updated dependencies [[`026b848`](https://github.com/mastra-ai/mastra/commit/026b8483fbf5b6d977be8f7e6aac8d15c75558ac), [`ffa553a`](https://github.com/mastra-ai/mastra/commit/ffa553a3edc1bd17d73669fba66d6b6f4ac10897)]:
+  - @mastra/core@1.0.0-beta.26
+  - @mastra/deployer@1.0.0-beta.26
+
 ## 1.0.0-beta.17
 
 ### Patch Changes
@@ -475,28 +499,4 @@
 
 ## 0.17.2-alpha.0
 
-### Patch Changes
-
-- Fix a bug where `mastra init` didn't work correctly when core dependencies were missing in the project ([#9070](https://github.com/mastra-ai/mastra/pull/9070))
-
-- Updated dependencies [[`69ff5d5`](https://github.com/mastra-ai/mastra/commit/69ff5d58e4bc4054ce76bbb25a8fa5d3177c49ea)]:
-  - @mastra/deployer@0.22.1-alpha.0
-  - @mastra/core@0.22.1-alpha.0
-
-## 0.17.1
-
-### Patch Changes
-
-- Add scorers to the default weather agent in the create command. ([#9042](https://github.com/mastra-ai/mastra/pull/9042))
-
-- Fix tool result in playground ([#9087](https://github.com/mastra-ai/mastra/pull/9087))
-
-- Use newer model id for anthropic during `create-mastra` ([#8996](https://github.com/mastra-ai/mastra/pull/8996))
-
-- Update peerdeps to 0.23.0-0 ([#9043](https://github.com/mastra-ai/mastra/pull/9043))
-
-- Updated dependencies [[`25305a2`](https://github.com/mastra-ai/mastra/commit/25305a2af1acf77cc2ac9237774ecd7d3caa31a1), [`c67ca32`](https://github.com/mastra-ai/mastra/commit/c67ca32e3c2cf69bfc146580770c720220ca44ac), [`efb5ed9`](https://github.com/mastra-ai/mastra/commit/efb5ed946ae7f410bc68c9430beb4b010afd25ec), [`dbc9e12`](https://github.com/mastra-ai/mastra/commit/dbc9e1216ba575ba59ead4afb727a01215f7de4f), [`99e41b9`](https://github.com/mastra-ai/mastra/commit/99e41b94957cdd25137d3ac12e94e8b21aa01b68), [`c28833c`](https://github.com/mastra-ai/mastra/commit/c28833c5b6d8e10eeffd7f7d39129d53b8bca240), [`8ea07b4`](https://github.com/mastra-ai/mastra/commit/8ea07b4bdc73e4218437dbb6dcb0f4b23e745a44), [`ba201b8`](https://github.com/mastra-ai/mastra/commit/ba201b8f8feac4c72350f2dbd52c13c7297ba7b0), [`f053e89`](https://github.com/mastra-ai/mastra/commit/f053e89160dbd0bd3333fc3492f68231b5c7c349), [`4fc4136`](https://github.com/mastra-ai/mastra/commit/4fc413652866a8d2240694fddb2562e9edbb70df), [`b78e04d`](https://github.com/mastra-ai/mastra/commit/b78e04d935a16ecb1e59c5c96e564903527edddd), [`d10baf5`](https://github.com/mastra-ai/mastra/commit/d10baf5a3c924f2a6654e23a3e318ed03f189b76), [`038c55a`](https://github.com/mastra-ai/mastra/commit/038c55a7090fc1b1513a966386d3072617f836ac), [`1eb156a`](https://github.com/mastra-ai/mastra/commit/1eb156ace499b34ab48bf23fb16f1affe6bb9c1c), [`182f045`](https://github.com/mastra-ai/mastra/commit/182f0458f25bd70aa774e64fd923c8a483eddbf1), [`9a1a485`](https://github.com/mastra-ai/mastra/commit/9a1a4859b855e37239f652bf14b1ecd1029b8c4e), [`9257233`](https://github.com/mastra-ai/mastra/commit/9257233c4ffce09b2bedc2a9adbd70d7a83fa8e2), [`7620d2b`](https://github.com/mastra-ai/mastra/commit/7620d2bddeb4fae4c3c0a0b4e672969795fca11a), [`b2365f0`](https://github.com/mastra-ai/mastra/commit/b2365f038dd4c5f06400428b224af963f399ad50), [`0f1a4c9`](https://github.com/mastra-ai/mastra/commit/0f1a4c984fb4b104b2f0b63ba18c9fa77f567700), [`9029ba3`](https://github.com/mastra-ai/mastra/commit/9029ba34459c8859fed4c6b73efd8e2d0021e7ba), [`426cc56`](https://github.com/mastra-ai/mastra/commit/426cc561c85ae76a112ded2385532a91f9f9f074), [`00931fb`](https://github.com/mastra-ai/mastra/commit/00931fb1a21aa42c4fbc20c2c40dd62466b8fc8f), [`e473bfe`](https://github.com/mastra-ai/mastra/commit/e473bfe416c0b8e876973c2b6a6f13c394b7a93f), [`b78e04d`](https://github.com/mastra-ai/mastra/commit/b78e04d935a16ecb1e59c5c96e564903527edddd), [`8ea07b4`](https://github.com/mastra-ai/mastra/commit/8ea07b4bdc73e4218437dbb6dcb0f4b23e745a44), [`084afad`](https://github.com/mastra-ai/mastra/commit/084afadff49b168d8b6104b43c77cecc96c48ac2), [`2db6160`](https://github.com/mastra-ai/mastra/commit/2db6160e2022ff8827c15d30157e684683b934b5), [`8aeea37`](https://github.com/mastra-ai/mastra/commit/8aeea37efdde347c635a67fed56794943b7f74ec), [`02fe153`](https://github.com/mastra-ai/mastra/commit/02fe15351d6021d214da48ec982a0e9e4150bcee), [`648e2ca`](https://github.com/mastra-ai/mastra/commit/648e2ca42da54838c6ccbdaadc6fadd808fa6b86), [`74567b3`](https://github.com/mastra-ai/mastra/commit/74567b3d237ae3915cd0bca3cf55fa0a64e4e4a4), [`b65c5e0`](https://github.com/mastra-ai/mastra/commit/b65c5e0fe6f3c390a9a8bbcf69304d972c3a4afb), [`15a1733`](https://github.com/mastra-ai/mastra/commit/15a1733074cee8bd37370e1af34cd818e89fa7ac), [`fc2a774`](https://github.com/mastra-ai/mastra/commit/fc2a77468981aaddc3e77f83f0c4ad4a4af140da), [`4e08933`](https://github.com/mastra-ai/mastra/commit/4e08933625464dfde178347af5b6278fcf34188e), [`10188d6`](https://github.com/mastra-ai/mastra/commit/10188d632a729010441f9c7e2a41eab60afccb23)]:
-  - @mastra/deployer@0.22.0
-  - @mastra/core@0.22.0
-
-... 6543 more lines hidden. See full changelog in package directory.
+... 6567 more lines hidden. See full changelog in package directory.

package/.docs/raw/guides/migrations/upgrade-to-v1/cli.mdx

@@ -5,7 +5,21 @@ description: "Learn how to migrate CLI changes when upgrading to v1."
 
 # CLI
 
-The CLI has been simplified by removing deployment commands, configuration flags, and starter files.
+The CLI has been simplified by removing deployment commands, configuration flags, and starter files. A new migration command has been added to help with database schema upgrades.
+
+## Added
+
+### `mastra migrate` command
+
+A new `mastra migrate` command helps run database migrations when upgrading Mastra versions. This is particularly useful when upgrading from older versions that may have data incompatibilities.
+
+```bash
+npx mastra migrate
+```
+
+The command bundles your project, connects to your configured storage, and runs any necessary migrations. Currently supports migrating duplicate spans entries that may prevent unique constraint creation.
+
+See the [Storage migration guide](/guides/v1/migrations/upgrade-to-v1/storage#duplicate-spans-migration) for details on when this migration is needed.
 
 ## Removed
 

package/.docs/raw/guides/migrations/upgrade-to-v1/storage.mdx

@@ -30,6 +30,60 @@ UPDATE mastra_scorers SET "requestContext" = "runtimeContext" WHERE "runtimeCont
 ALTER TABLE mastra_scorers DROP COLUMN "runtimeContext";
 ```
 
+### Duplicate spans migration
+
+If you're upgrading from an older version of Mastra, you may have duplicate `(traceId, spanId)` entries in your `mastra_spans` table. V1 adds a unique constraint on these columns to ensure data integrity, but this constraint cannot be added if duplicates exist.
+
+:::note[Who needs this migration]
+Only if you have existing spans data from Mastra versions prior to v1 and encounter errors about duplicate key violations or constraint creation failures.
+:::
+
+:::important[What breaks without it]
+The storage initialization may fail when trying to add the unique constraint, or you may see errors like "duplicate key value violates unique constraint".
+:::
+
+**Option 1: Use the CLI (Recommended)**
+
+Run the migration command which automatically deduplicates spans and adds the constraint:
+
+```bash
+npx mastra migrate
+```
+
+The CLI bundles your project, connects to your configured storage, and runs the migration. It keeps the most complete record (based on `endTime` and attributes) when removing duplicates.
+
+**Option 2: Manual SQL (PostgreSQL)**
+
+If you prefer to run the migration manually:
+
+```sql
+-- Remove duplicates, keeping the most complete record
+DELETE FROM mastra_spans a USING mastra_spans b
+WHERE a.ctid < b.ctid
+  AND a."traceId" = b."traceId"
+  AND a."spanId" = b."spanId";
+
+-- Add the unique constraint
+ALTER TABLE mastra_spans ADD CONSTRAINT mastra_spans_trace_span_unique UNIQUE ("traceId", "spanId");
+```
+
+**Option 3: Manual migration (Other databases)**
+
+For ClickHouse, LibSQL, MongoDB, or MSSQL, use the programmatic API:
+
+```typescript
+const storage = mastra.getStorage();
+const observabilityStore = await storage.getStore('observability');
+
+// Check if migration is needed
+const status = await observabilityStore?.checkSpansMigrationStatus();
+console.log(status);
+
+// Run the migration
+const result = await observabilityStore?.migrateSpans();
+console.log(result);
+```
+
 ### JSON columns (TEXT → JSONB)
 
 **PostgreSQL only.** The `metadata` column in `mastra_threads` and `snapshot` column in `mastra_workflow_snapshot` changed from TEXT to JSONB.
@@ -50,19 +104,19 @@ USING snapshot::jsonb;
 
 ## Added
 
-### Storage composition in MastraStorage
+### Storage composition in MastraCompositeStore
 
-`MastraStorage` can now compose storage domains from different adapters. Use it when you need different databases for different purposes - for example, PostgreSQL for memory and workflows, but a specialized database for observability.
+`MastraCompositeStore` can now compose storage domains from different adapters. Use it when you need different databases for different purposes - for example, PostgreSQL for memory and workflows, but a specialized database for observability.
 
 ```typescript
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { MemoryLibSQL } from "@mastra/libsql";
 import { Mastra } from "@mastra/core";
 
 // Compose domains from different stores
 const mastra = new Mastra({
-  storage: new MastraStorage({
+  storage: new MastraCompositeStore({
     id: "composite",
     domains: {
       memory: new MemoryLibSQL({ url: "file:./local.db" }),
@@ -77,6 +131,36 @@ See the [Storage Composition reference](/reference/v1/storage/composite) for mor
 
 ## Changed
 
+### `MastraStorage` renamed to `MastraCompositeStore`
+
+The `MastraStorage` class has been renamed to `MastraCompositeStore` to better reflect its role as a composite storage implementation that routes different domains to different underlying stores. This avoids confusion with the general "Mastra Storage" concept (the `storage` property on the Mastra instance).
+
+The old `MastraStorage` name remains available as a deprecated alias for backward compatibility, but will be removed in a future version.
+
+To migrate, update your imports and instantiation:
+
+```diff
+- import { MastraStorage } from "@mastra/core/storage";
++ import { MastraCompositeStore } from "@mastra/core/storage";
+  import { MemoryLibSQL } from "@mastra/libsql";
+  import { WorkflowsPG } from "@mastra/pg";
+
+  export const mastra = new Mastra({
+-   storage: new MastraStorage({
++   storage: new MastraCompositeStore({
+      id: "composite",
+      domains: {
+        memory: new MemoryLibSQL({ url: "file:./memory.db" }),
+        workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+      },
+    }),
+  });
+```
+
+:::note
+If you're using a single store implementation (like `PostgresStore` or `LibSQLStore`) directly, no changes are needed. This only affects code that explicitly uses `MastraStorage` for composite storage.
+:::
+
 ### Required `id` property for storage instances
 
 Storage instances now require an `id` property. This unique identifier is used for tracking and managing storage instances within Mastra. The `id` should be a descriptive, unique string for each storage instance in your application.

package/.docs/raw/memory/storage.mdx

@@ -74,17 +74,17 @@ This is useful when all primitives share the same storage backend and have simil
 
 #### Composite storage
 
-Add storage to your Mastra instance using `MastraStorage` and configure individual storage domains to use different storage providers.
+Add storage to your Mastra instance using `MastraCompositeStore` and configure individual storage domains to use different storage providers.
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
-import { MastraStorage } from "@mastra/core/storage";
+import { MastraCompositeStore } from "@mastra/core/storage";
 import { MemoryLibSQL } from "@mastra/libsql";
 import { WorkflowsPG } from "@mastra/pg";
 import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
 
 export const mastra = new Mastra({
-  storage: new MastraStorage({
+  storage: new MastraCompositeStore({
     id: "composite",
     domains: {
       memory: new MemoryLibSQL({ url: "file:./memory.db" }),

package/.docs/raw/reference/cli/mastra.mdx

@@ -228,29 +228,45 @@ Do not include example code. Useful when using the `--default` flag.
 
 Configure your code editor with Mastra's MCP server. Choose from: `"cursor" | "cursor-global" | "windsurf" | "vscode"`.
 
+## `mastra migrate`
+
+Runs database migrations to update your storage schema. This command is useful when upgrading Mastra versions that include storage schema changes.
+
+The command bundles your project, connects to your configured storage backend, and executes any pending migrations. Currently supports:
+
+- **Duplicate spans migration**: Removes duplicate `(traceId, spanId)` entries and adds a unique constraint to ensure data integrity.
+
+```bash
+mastra migrate
+```
+
+See the [Storage migration guide](/guides/v1/migrations/upgrade-to-v1/storage#duplicate-spans-migration) for details on when migrations are needed.
+
+It accepts [common flags][common-flags].
+
 ## Common flags
 
 ### `--dir`
 
-**Available in:** `dev`, `build`, `lint`
+**Available in:** `dev`, `build`, `lint`, `migrate`
 
 The path to your Mastra folder. Defaults to `src/mastra`.
 
 ### `--debug`
 
-**Available in:** `dev`, `build`
+**Available in:** `dev`, `build`, `migrate`
 
 Enable verbose logging for Mastra's internals. Defaults to `false`.
 
 ### `--env`
 
-**Available in:** `dev`, `start`, `studio`
+**Available in:** `dev`, `start`, `studio`, `migrate`
 
 Custom environment variables file to include. By default, includes `.env.development`, `.env.local`, and `.env`.
 
 ### `--root`
 
-**Available in:** `dev`, `build`, `lint`
+**Available in:** `dev`, `build`, `lint`, `migrate`
 
 Path to your root folder. Defaults to `process.cwd()`.
 

package/.docs/raw/reference/configuration.mdx

@@ -307,7 +307,7 @@ export const mastra = new Mastra({
 
 ### storage
 
-**Type:** `MastraStorage`
+**Type:** `MastraCompositeStore`
 
 Storage provider for persisting application data. Used by memory, workflows, traces, and other components that require persistence. Mastra supports multiple database backends including PostgreSQL, MongoDB, libSQL, and more.
 

package/.docs/raw/reference/core/getStorage.mdx

@@ -25,7 +25,7 @@ This method does not accept any parameters.
   content={[
     {
       name: "storage",
-      type: "MastraStorage | undefined",
+      type: "MastraCompositeStore | undefined",
       description:
         "The configured storage instance, or undefined if no storage has been configured.",
     },

package/.docs/raw/reference/core/mastra-class.mdx

@@ -59,7 +59,7 @@ Visit the [Configuration reference](/reference/v1/configuration) for detailed do
     },
     {
       name: "storage",
-      type: "MastraStorage",
+      type: "MastraCompositeStore",
       description: "Storage engine instance for persisting data",
       isOptional: true,
     },

package/.docs/raw/reference/core/setStorage.mdx

@@ -7,7 +7,7 @@ packages:
 
 # Mastra.setStorage()
 
-The `.setStorage()` method is used to set the storage instance for the Mastra instance. This method accepts a single `MastraStorage` parameter.
+The `.setStorage()` method is used to set the storage instance for the Mastra instance. This method accepts a single `MastraCompositeStore` parameter.
 
 ## Usage example
 
@@ -26,7 +26,7 @@ mastra.setStorage(
   content={[
     {
       name: "storage",
-      type: "MastraStorage",
+      type: "MastraCompositeStore",
       description: "The storage instance to set for the Mastra instance.",
     },
   ]}