migration-helper

用途：在 Convex 中安全迁移架构与数据，处理破坏性变更，避免应用中断。Convex 不会自动迁移数据，新增可选字段或新表属安全变更；必填字段、改类型、重命名、拆表合表等需要迁移代码。主要能力：给出从可选字段开始、回填、再设为必填的步骤；提供内部 mutation 编写回填、批量处理、分页与游标、定时任务、双写等模式；说明如何验证进度并列出常见陷阱。使用方式：先以可选或叠加方式加入新结构，编写 internalMutation 执行迁移，通过仪表盘或 CLI 运行，例如 npx convex run migrations:backfillEmails；大批量可分批次、多次运行或定时执行；验证完成后更新应用代码、部署，最后从架构中移除旧字段并清理迁移代码。适用场景：为已有表加必填字段、字段类型变更、标签数组转关系表、字段重命名等。限制：迁移需手动编写并在正确时机运行，文档要求先在开发环境测试、避免单个事务处理大表、不要过早设必填或删除旧字段；具体部署与回滚细节资料未提供。