convex-migration-helper

Convex 迁移助手

在进行破坏性更改时，安全地迁移 Convex 架构和数据。

适用场景

• 为现有表添加新的必填字段
• 更改字段类型或结构
• 拆分或合并表
• 重命名或删除字段
• 将嵌套数据迁移为关系型数据

不适用场景

• 全新架构，在生产环境或开发环境中均没有现有数据
• 添加无需回填的可选字段
• 添加没有现有数据需要迁移的新表
• 添加或删除索引，且不影响正确性
• 无需迁移时关于 Convex 架构设计的问题

核心概念

架构验证决定工作流

Convex 不允许部署与现有数据不匹配的架构。 这是决定每次迁移方式的基本约束：

• 如果现有文档没有某个字段，就不能添加必填字段
• 如果现有文档仍使用旧类型，就不能更改字段类型
• 如果现有文档仍包含某个字段，就不能从架构中移除该字段

这意味着迁移遵循可预测的模式：扩展架构、迁移数据、收紧架构。

在线迁移

Convex 迁移会在线运行，这意味着应用在数据分批异步更新期间仍会继续处理请求。在迁移期间，代码必须能够处理新旧两种数据格式。

优先新增字段，而非更改类型

更改数据结构时，应创建新字段，而不是修改现有字段。这样过渡更安全，也更容易回滚。

不要删除数据

除非确定无误，否则应优先弃用字段，而不是删除字段。将字段标记为 v.optional，并添加代码注释，说明该字段已弃用以及它原先存在的原因。

安全更改（无需迁移）

添加可选字段

// Before
users: defineTable({
  name: v.string(),
});

// After - safe, new field is optional
users: defineTable({
  name: v.string(),
  bio: v.optional(v.string()),
});

添加新表

posts: defineTable({
  userId: v.id("users"),
  title: v.string(),
}).index("by_user", ["userId"]);

添加索引

users: defineTable({
  name: v.string(),
  email: v.string(),
}).index("by_email", ["email"]);

破坏性更改：部署工作流

每次破坏性迁移都遵循相同的多次部署模式：

部署 1 - 扩展架构：

1. 更新架构，使其同时允许新旧格式（例如，添加新的可选字段）
2. 更新代码，使其在读取时能够处理两种格式
3. 更新代码，使其为新文档写入新格式
4. 部署

部署之间 - 迁移数据：

5. 运行迁移，为现有文档回填数据
6. 验证所有文档均已迁移

部署 2 - 收紧架构：

7. 更新架构，使其只要求新格式
8. 移除处理旧格式的代码
9. 部署

使用迁移组件

对于任何非简单迁移，请使用 @convex-dev/migrations 组件。它会处理分批、基于游标的分页、状态跟踪、失败后恢复、试运行和进度监控。

请参阅 references/migrations-component.md，了解如何安装和设置组件、定义和直接运行迁移（使用 npx convex run migrations:myMigration）、进行试运行、监控状态以及配置选项。

常见迁移模式

请参阅 references/migration-patterns.md，了解包含代码示例的完整模式，涵盖：

• 添加必填字段
• 删除字段
• 更改字段类型
• 将嵌套数据拆分到单独的表中
• 清理孤立文档
• 零停机策略（双写、双读）
• 小表的快捷做法（不使用组件，直接使用单个 internalMutation）
• 验证迁移是否完成

常见陷阱

1. 在迁移数据前将字段设为必填项：由于现有文档缺少该字段，Convex 会拒绝部署。请始终先放宽 schema。
2. 对大型表使用 .collect()：这会触及事务限制或导致超时。请使用迁移组件进行适当的分页批处理。只有在确定表很小的情况下，使用 .collect() 才安全。
3. 迁移前没有写入新格式：迁移期间创建的文档会被遗漏，导致迁移“完成”后仍有数据未迁移。
4. 跳过试运行：使用 dryRun: true，在将更改提交到生产数据前验证迁移逻辑。这样能在问题影响真实文档前发现错误。
5. 过早删除字段：建议使用 v.optional 并添加注释，将字段标记为弃用。只有在确认不再需要该数据且没有代码引用该字段后，才将其删除。
6. 使用 crons 处理迁移批次：迁移组件会通过递归调度在内部处理批次。使用 crons 则需要手动清理，并额外部署一次才能移除。

迁移检查清单

• 确定会造成不兼容的更改，并规划多次部署工作流
• 更新 schema，使其同时允许旧格式和新格式
• 更新代码，使其读取时能处理两种格式
• 更新代码，使新文档采用新格式
• 部署放宽后的 schema 和更新后的代码
• 使用 @convex-dev/migrations 组件定义迁移
• 使用 npx convex run migrations:myMigration '{"dryRun": true}' 进行测试
• 直接运行迁移：npx convex run migrations:myMigration，并监控状态
• 验证所有文档均已迁移
• 更新 schema，仅要求新格式
• 清理用于处理旧格式的代码
• 部署最终的 schema 和代码
• 确认稳定后移除迁移代码