mcpField
C
convex-migrate-rehearse

convex-migrate-rehearse

github.com/convex数据与数据库6937.0k 次安装1 天前更新
代码仓库

关于 convex-migrate-rehearse

此技能指导 Convex 开发者先在由生产快照填充的预览部署中演练架构变更，再将相同迁移步骤应用到生产环境，涵盖回填、验证与回滚注意事项。

主要功能

  1. 01用生产快照填充预览部署
  2. 02先部署可选字段架构
  3. 03执行分批且可恢复的回填
  4. 04收紧约束前验证迁移数据
  5. 05将已验证步骤应用到生产
  6. 06保护快照并规划回滚

适用场景

  1. 01在不影响生产的情况下测试架构一致性
  2. 02要求字段必填前回填现有记录
  3. 03在迁移后的数据上验证应用行为

MCP 相关

可通过 MCP `run` 或 `runOneoffQuery` 在预览部署上运行函数，以验证迁移结果。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/convex/agent-skills --skill convex-migrate-rehearse

安装后在 Claude Code 中输入/convex-migrate-rehearse确认已加载。

详细介绍

在上线前用预览环境演练架构变更

在 Convex 上推送架构时，会根据新架构验证每一份现有文档；如果任何一条记录不符合要求，推送就会失败——这是一道真正的数据一致性门槛。安全使用这道门槛的方式，是让它在演练副本上失败，而不是在生产环境中失败。此功能会将预览部署用作副本：用生产环境快照为其填充数据，推送新架构并在那里运行回填，观察门槛检查结果，只有检查通过后才进行推广。此流程结合了 deploy-guard（目标分类）、migrate（先放宽、再收紧的模式）和 @convex-dev/migrations（分批、可恢复的回填）。

工作流

  1. 前置条件：预览部署需要 Preview Deploy Key（dashboard → Project Settings → Deploy Keys → Preview），并且必须在任何 --preview-create/--preview-name 部署之前将其导出为 CONVEX_DEPLOY_KEY——普通的 npx convex login 会话无法创建预览部署，而且此功能为付费层级专属。如果没有可用的预览密钥，请改为在使用快照填充数据的个人开发部署上演练，并明确说明这一点。
  2. 防护：使用 deploy-guard 分类并说明 SOURCE（正在读取的生产环境）和最终 TARGET（将要变更的生产环境）；提前取得对生产环境推广操作的明确确认，并确认计划。
  3. 以只读方式对源数据创建快照：npx convex export --path snapshot.zip（针对存放真实数据的部署执行；只有迁移涉及文件时才添加 --include-file-storage）。这是读取操作，不会更改任何内容。
  4. 从变更前的代码创建预览部署——必须在编辑 schema.ts 之前执行，以便预览部署从符合快照数据的架构开始：npx convex deploy --preview-create migrate-<slug>（需要预览密钥；约 5 天后自动过期）。为其填充数据：npx convex import snapshot.zip --deployment migrate-<slug>（导入时通过 --deployment 指定部署名称；import 不支持 --preview-name 标志）。由于数据仍符合旧架构，导入会成功。
  5. 按 migrate 的顺序在预览部署上演练——每次推送都使用 npx convex deploy --preview-name migrate-<slug>（重新部署到同一个预览部署，并保留其数据；不要使用目标为个人开发部署的 convex dev）：(a) 将新增或变更的字段设为可选并部署——如果现有记录不符合要求，推送会在副本上于此处失败，并显示不符合要求的数据形态；修复后重新推送，直到通过。(b) 编写 @convex-dev/migrations 回填，并在预览部署上运行；验证每一条记录现在都有效。(c) 收紧验证器（改为必填或缩小联合类型范围），然后再次部署——回填运行后，门槛检查就会通过。
  6. 在预览部署上验证：使用迁移后的数据运行应用函数（将 MCP run/runOneoffQuery 指向预览部署，或运行冒烟查询），确认行为和数据形态。
  7. 仅在取得第 1 步所述的明确确认后才进行推广：对生产环境应用相同顺序（可选架构 → 回填 → 收紧）。由于该流程已在符合生产数据形态的数据上成功运行，生产环境的推送只是重复一次已验证的流程。保留快照作为回滚产物（npx convex import snapshot.zip --replace --prod）；明确说明快照之后写入的数据会丢失，因此应缩短推广操作的时间窗口。
  8. 清理：预览部署会自动过期；完成后删除本地快照（其中包含真实数据，应视为敏感信息，切勿提交）。

规则

  • 在编辑 schema.ts 之前，先基于变更前的代码创建预览并生成快照，这样导入时符合规范，随后推送变更时，一致性门禁会在副本（而非生产环境）上失败；每次推送预览都使用 deploy --preview-name，导入时用 --deployment 指定目标。
  • 每次都按迁移顺序执行：可选字段 → 推送 → 回填 → 验证 → 收紧 → 推送；跳过“先设为可选”会导致第一次推送就拒绝现有行。
  • 提升到生产环境前，必须通过 deploy-guard 再次明确确认；这只是重复已验证的预览流程，而不是新的尝试。
  • 将生产快照保留为回滚产物；明确说明恢复快照会丢失快照之后写入的数据，因此应缩短提升窗口。
  • 将导出的快照视为敏感的真实数据：完成后在本地删除，绝不要提交。
  • 回填应通过 @convex-dev/migrations 执行（支持批处理、可恢复、可试运行），不要对整张表使用临时的一次性 mutation。
  • 这是演练并提升到生产环境的流程；若只需在没有实时数据的情况下说明“先设为可选，再收紧”，请使用 migrate。

评论

支持 Markdown