SuperAPI AI 工具集

convex-migrate-rehearse

编程与开发

查看项目

更新于 10-15 21:51

技能介绍

用途:在真正改动生产数据前,先在用生产快照预置的预览部署上排练 schema 变更与回填,通过 Convex 的文档一致性校验后再推广。

主要能力与流程:

  1. 前置:预览部署需要 Preview Deploy Key(控制台 → Project Settings → Deploy Keys → Preview)并导出为 CONVEX_DEPLOY_KEY,属于付费层功能;无预览密钥时可退化为在个人 dev 部署上排练。
  2. 守卫:分类并声明数据来源(生产)与最终目标(生产),事先取得对生产推广的明确同意。
  3. 快照:npx convex export --path snapshot.zip,只读;涉及文件存储时加 --include-file-storage。
  4. 创建预览:必须在编辑 schema.ts 之前,用变更前代码创建,使快照数据可导入。npx convex deploy --preview-create migrate-<slug>;导入用 npx convex import snapshot.zip --deployment migrate-<slug>(import 无 --preview-name)。
  5. 排练顺序:每次推送用 npx convex deploy --preview-name migrate-<slug>(不是 convex dev)。先把新字段设为可选并部署,若旧数据不合规则在此失败,修复重推;再依据 @convex-dev/migrations 编写回填并运行;随后收紧校验器(必填/收窄联合类型)再次部署。
  6. 验证:在预览上运行应用函数(如 MCP run/runOneoffQuery 或冒烟查询)确认行为与数据形态。
  7. 推广:取得新的明确同意后,对生产重复相同顺序(可选 schema → 回填 → 收紧)。保留快照作为回滚产物(npx convex import snapshot.zip --replace --prod),但需说明快照后写入的数据会丢失,因此推广窗口要短。
  8. 清理:预览自动过期;本地快照含真实数据,视为敏感,用完删除,切勿提交。

限制:预览功能需付费层且约 5 天自动过期;必须遵循“先可选、再回填、后收紧”的顺序,否则首次推送会被现有行拒绝;回填应使用 @convex-dev/migrations(批量、可恢复、可试运行),而非一次性全表 mutation。