用途:在 Convex 中做破坏性模式变更时,安全迁移模式与数据。触发场景包括给已有表加必填字段、改字段类型或结构、拆分或合并表、重命名字段、从嵌套数据迁移到关系型数据。
主要原则:Convex 不会自动迁移数据;新增可选字段或新表属安全变更,无需迁移;必填字段、类型变更等破坏性变更必须写迁移代码;迁移应保持零停机。安全变更包括加可选字段、加新表、加索引。
常见模式与用法:加必填字段分四步——先定义为可选、写 internalMutation 回填、运行迁移、再改为必填,运行命令为 npx convex run migrations:backfillEmails。重命名字段分四步:加新字段(可选)、用 internalMutation 复制数据、改模式去掉旧字段、更新全部代码。还提供批量处理(用 cursor 与 batchSize 分批)、双写模式(过渡期同时写新旧结构)、定时迁移(cronJobs 定时执行 internal.migrations.migrateBatch)等模式,并给出一份迁移清单。
限制与注意:不要一上来就把字段设为必填,应先可选再回填;不要用单个事务迁移,大表要分批;不要忘记更新使用旧字段的查询;旧字段删除不要过早,需等数据全部迁完;务必先在开发环境充分测试。具体平台与定价信息暂未提供。