用途
Convex Migration Helper 用于指导在 Convex 数据库中进行破坏性 schema 变更时的安全迁移。Convex 不会自动迁移已有数据，因此当 schema 变更影响现有文档时，需要借助该技能规划并编写迁移代码。
何时使用
- 向已有表添加新的必填字段
- 更改字段类型或结构
- 拆分或合并表
- 重命名字段
- 从嵌套数据迁移为关系型数据
迁移原则
- 无自动迁移：Convex 不会自动迁移数据
- 附加式变更安全：添加可选字段或新表是安全的
- 破坏性变更需要代码：必填字段、类型变更需要编写迁移逻辑
- 零停机：迁移期间保持应用可用
安全变更（无需迁移）
- 添加可选字段，例如
bio: v.optional(v.string()) - 添加全新表
- 随时添加索引
破坏性变更（需要迁移）
- 添加必填字段：先加为可选，回填数据，再改为必填
- 更改字段类型：例如把
tags数组迁移为独立的表与关联表，期间保留旧字段为可选 - 重命名字段：先加新字段（可选），复制数据，更新 schema，再更新代码
典型迁移步骤（以添加必填字段为例）：
- 在 schema 中先以可选添加字段
- 编写 internalMutation 回填数据，如
backfillEmails - 通过
npx convex run migrations:backfillEmails或仪表盘执行 - 数据迁移完成后将字段改为必填
迁移模式
- 批处理：对大数据表使用
take(batchSize)分批处理，返回已处理数量和是否还有剩余 - 定时迁移：通过
convex/crons.ts使用cronJobs定时分批执行迁移 - 双写模式：过渡期同时写入旧字段和新结构，迁移完成后再移除旧写入
验证与检查清单
文档提供一个 verifyMigration 查询示例，统计总数、已迁移数、剩余数和完成百分比。迁移检查清单包括：识别破坏性变更、以可选或附加方式添加新结构、编写内部 mutation、在样本数据上测试、大数据集分批执行、验证全部记录已更新、更新应用代码、部署、从 schema 移除旧字段、清理迁移代码。
常见陷阱
- 不要立即把字段设为必填，应先设为可选
- 不要在单个事务中迁移全部数据，大数据量应分批
- 不要忘记更新使用旧字段的查询代码
- 不要过早删除旧字段，应等全部数据迁移完成
- 应先在开发环境充分测试
平台与获取方式
该技能页面地址为 https://www.skills.sh/convex/convex-agent-plugins/migration-helper，来源为 convex/convex-agent-plugins。收费方式、安装命令和具体使用方式暂未提供。