用途:在不造成停机的前提下修改 Convex 线上 schema,并生成配套的分批回填,使每次部署都能通过校验。核心规则是 schema 必须描述当前已存在的文档,而不是期望的文档:先改数据,再收紧校验器。Convex 没有迁移文件或 migrate 命令,npx convex dev 会推送 schema 并校验所有现有文档,但不会自动转换数据。
适用场景:为已有数据的表添加本应必填的字段;重命名、改类型或删除字段;拆分或合并表;schema 编辑后 npx convex dev 报 Schema validation failed;回填行数超过单个 mutation 能处理的范围。
安全流程共六步:1) 在 convex/schema.ts 中把字段设为可选(或新增 v.optional 字段);2) 用 npx convex dev 部署,更新读取方处理 undefined、写入方产出新结构;3) 用 internalMutation 或 migrations 组件分批回填;4) 把校验器改为最终形态;5) 再次部署;6) 清理回退代码、回填函数和过期索引。第 1、2 步必须先于第 3 步上线。
手写回填:用 internalMutation 配合 paginate 分页,只 patch 仍需处理的文档,再用 continue cursor 通过 ctx.scheduler.runAfter(0, internal....) 重新调度自身,每批独立事务。用 npx convex run migrations:backfillAvatarUrl '{"cursor": null}' 启动。回填必须幂等,且只能用 internalMutation,不能用公开 mutation。
组件方式:@convex-dev/migrations 封装上述模式,额外提供每个迁移的持久化进度、状态检查、dry run、取消和有序执行。项目生命周期内迁移较多、需确认生产是否已完成、想先 dry run 或需固定顺序时使用。支持 npx convex run migrations:addDefaultRole '{"dryRun": true}'。小表一次性回填无需组件。
部署报错解读:错误会给出表名、违规文档 id 和不匹配字段。修复方式不是删除文档,而是先包 v.optional、部署、回填,再移除 v.optional;类型不符时先放宽为 v.union,回填转换后再收窄。不要用 { schemaValidation: false } 绕过校验。
常见错误:一次部署就加必填字段;回填先于新写入方部署;用 .collect() 拉全表;用公开 mutation 回填;patch 不幂等;读取方未切换就删旧字段;用 .filter() 找未迁移行;关闭 schemaValidation;先在生产跑回填。
限制:资料未提供该技能的安装命令、收费与平台信息。