convex-migration-helper by get-convex/agent-skills
npx skills add https://github.com/get-convex/agent-skills --skill convex-migration-helper安全地进行破坏性更改时迁移 Convex 模式和数据。
Convex 不允许部署与静态数据不匹配的模式。这是塑造每次迁移的基本约束:
这意味着迁移遵循一个可预测的模式:放宽模式,迁移数据,收紧模式。
Convex 迁移在线运行,这意味着应用程序在数据异步批量更新的同时继续处理请求。在迁移窗口期间,您的代码必须同时处理新旧数据格式。
更改数据形状时,应创建新字段而不是修改现有字段。这使过渡更安全且更容易回滚。
除非您确定,否则优先弃用字段而不是删除它们。将字段标记为 v.optional 并添加代码注释,说明其已弃用及其存在的原因。
// 之前
users: defineTable({
name: v.string(),
})
// 之后 - 安全,新字段是可选的
users: defineTable({
name: v.string(),
bio: v.optional(v.string()),
})
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
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 - 放宽模式:
部署之间 - 迁移数据:
部署 2 - 收紧模式:
对于任何非简单的迁移,请使用 @convex-dev/migrations 组件。它处理批处理、基于游标的分页、状态跟踪、失败恢复、试运行和进度监控。
有关安装、设置、定义和运行迁移、试运行、状态监控和配置选项,请参阅 references/migrations-component.md。
有关包含代码示例的完整模式,请参阅 references/migration-patterns.md,涵盖:
.collect():会达到事务限制或导致超时。使用迁移组件进行适当的批量分页。.collect() 仅对您知道是小表的情况安全。dryRun: true 在将更改提交到生产数据之前验证迁移逻辑。在触及真实文档之前捕获错误。v.optional 和注释进行弃用。只有在确信不再需要该数据且没有代码引用它之后才删除。@convex-dev/migrations 组件定义迁移dryRun: true 进行测试每周安装量
6.7K
代码仓库
GitHub 星标数
15
首次出现
10 天前
安全审计
安装于
codex6.7K
cursor6.7K
kimi-cli6.7K
amp6.7K
github-copilot6.7K
opencode6.7K
Safely migrate Convex schemas and data when making breaking changes.
Convex will not let you deploy a schema that does not match the data at rest. This is the fundamental constraint that shapes every migration:
This means migrations follow a predictable pattern: widen the schema, migrate the data, narrow the schema.
Convex migrations run online, meaning the app continues serving requests while data is updated asynchronously in batches. During the migration window, your code must handle both old and new data formats.
When changing the shape of data, create a new field rather than modifying an existing one. This makes the transition safer and easier to roll back.
Unless you are certain, prefer deprecating fields over deleting them. Mark the field as v.optional and add a code comment explaining it is deprecated and why it existed.
// 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"])
Every breaking migration follows the same multi-deploy pattern:
Deploy 1 - Widen the schema:
Between deploys - Migrate data:
Deploy 2 - Narrow the schema:
For any non-trivial migration, use the @convex-dev/migrations component. It handles batching, cursor-based pagination, state tracking, resume from failure, dry runs, and progress monitoring.
See references/migrations-component.md for installation, setup, defining and running migrations, dry runs, status monitoring, and configuration options.
See references/migration-patterns.md for complete patterns with code examples covering:
.collect() on large tables: Hits transaction limits or causes timeouts. Use the migrations component for proper batched pagination. .collect() is only safe for tables you know are small.dryRun: true to validate migration logic before committing changes to production data. Catches bugs before they touch real documents.v.optional and a comment. Only delete after you are confident the data is no longer needed and no code references it.@convex-dev/migrations componentdryRun: trueWeekly Installs
6.7K
Repository
GitHub Stars
15
First Seen
10 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex6.7K
cursor6.7K
kimi-cli6.7K
amp6.7K
github-copilot6.7K
opencode6.7K
99,500 周安装