convex-migration-helper

Convex Migration Helper 是一套面向 Convex 数据库的 schema 与数据迁移规划指南，核心采用“放宽—迁移—收窄”（widen-migrate-narrow）的多轮部署流程，并推荐使用 @convex-dev/migrations 组件处理分批迁移。它帮助开发者在修改表结构、字段类型、字段名称、拆分表或表合并等破坏性变更时，安全地完成数据回填与格式过渡，避免因 schema 校验不通过而无法部署。\n\n主要用途\n该工具适用于以下场景：向已有表添加必填字段、更改字段类型或结构、拆分或合并表、重命名字段或删除字段、从嵌套数据迁移到关系型数据。不适合用于：全新 schema 且生产或开发环境没有存量数据、添加无需回填的可选字段、添加没有存量数据需要迁移的新表、增删索引且不涉及正确性问题、以及仅咨询 Convex schema 设计但没有迁移需求的情况。\n\n关键概念\nConvex 不允许部署与存量数据不匹配的 schema，这是所有迁移的根本约束：不能添加存量文档没有的必填字段；不能更改存量文档仍为旧类型的字段类型；不能从 schema 中删除存量文档仍存在的字段。因此迁移遵循固定模式：先放宽 schema，再迁移数据，最后收窄 schema。迁移为在线迁移，应用在数据异步分批更新期间继续服务请求，过渡窗口内代码必须同时处理新旧两种数据格式。变更数据形态时，优先新增字段而非修改已有字段；除非确定，优先弃用字段而非删除字段，可标记为 v.optional 并添加注释说明。\n\n安全变更（无需迁移）\n添加可选字段（如 bio: v.optional(v.string())）、添加新表、添加索引均属安全变更。\n\n破坏性变更的部署流程\n每次破坏性迁移遵循同一多轮部署模式：部署 1 放宽 schema，让新旧格式并存，更新代码以在读取时兼容两种格式，并让新文档写入新格式；部署之后运行迁移回填存量文档并验证全部迁移完成；部署 2 收窄 schema，只要求新格式，移除处理旧格式的代码。\n\n使用 migrations 组件\n对于任何非平凡迁移，使用 @convex-dev/migrations 组件，它处理分批、基于游标的分页、状态跟踪、失败恢复、试运行与进度监控。可直接通过 npx convex run migrations:myMigration 运行迁移，并支持 dry run、状态监控与配置选项（详见 references/migrations-component.md）。\n\n常见迁移模式\nreferences/migration-patterns.md 提供完整模式与代码示例，涵盖：添加必填字段、删除字段、更改字段类型、将嵌套数据拆分为单独的表、清理孤立文档、零停机策略（双写、双读）、小表捷径（不使用组件、单个 internalMutation）、验证迁移完成。\n\n常见陷阱\n在迁移数据前将字段设为必填会导致部署被拒；对大表使用 .collect() 会触及事务限制或超时，应使用 migrations 组件进行分批分页；迁移前未写入新格式会导致迁移窗口期内创建的文档被遗漏；跳过 dry run 会让潜在缺陷触碰生产数据；过早删除字段、使用 cron 执行迁移批次（组件内部通过递归调度处理分批，cron 需要手动清理并多一次部署移除）均不推荐。\n\n迁移检查清单\n识别破坏性变更并规划多轮部署；更新 schema 允许新旧格式；更新代码读取时兼容两种格式；更新代码让新文档写入新格式；部署放宽后的 schema 和更新后的代码；使用 @convex-dev/migrations 组件定义迁移；用 npx convex run migrations:myMigration '{"dryRun": true}' 测试；用 npx convex run migrations:myMigration 直接运行并监控状态；验证所有文档已迁移；更新 schema 只要求新格式；清理处理旧格式的代码；部署最终 schema 和代码；确认稳定后移除迁移代码。