## Description
When upgrading from older versions, existing duplicate `(traceId,
spanId)` combinations in the spans table could prevent the unique
constraint/index from being created. This PR adds automatic
deduplication during migration for all storage providers with
observability support.
**Deduplication priority:**
1. Keep completed spans (`endedAt` IS NOT NULL) over incomplete
2. Keep most recently updated (`updatedAt`)
3. Keep most recently created (`createdAt`) as tiebreaker
**Stores fixed:**
- `@mastra/pg` - PostgreSQL
- `@mastra/mongodb` - MongoDB
- `@mastra/mssql` - Microsoft SQL Server
- `@mastra/libsql` - LibSQL
- `@mastra/clickhouse` - ClickHouse
## Related Issue(s)
Fixes#11840
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update
## Checklist
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Deduplicates existing duplicate span records during upgrades using
prioritized rules (completed, newest updated, createdAt tiebreaker).
* **New Features**
* New mastra migrate CLI and commands to check migration status and run
idempotent span deduplication and constraint enforcement across
supported stores.
* Store APIs to query migration status and perform safe migrations.
* **Chores**
* Memory-safe, batched migration flows and clearer migration-required
errors with actionable guidance.
* **Tests**
* Extensive DB-specific and end-to-end migration tests.
* **Docs**
* Updated migration guides and CLI documentation for the migrate
workflow.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Eric Pinzur <2641606+epinzur@users.noreply.github.com>
Co-authored-by: Eric Pinzur <epinzur@gmail.com>
Co-authored-by: Lennart <lekoarts@gmail.com>