convex-migrate

get-convex/agent-skills/convex-migrate

此技能指导如何在不破坏现有数据的情况下更改已部署的 schema。首先将新字段设为可选，以便部署不会拒绝现有行。然后安装 @convex-dev/migrations，编写迁移来回填或转换现有行。运行迁移并验证所有行有效后，再收紧验证器（将字段设为必填）。关键规则包括：在回填完成前切勿收紧验证器，否则会拒绝现有行并破坏实时应用；始终先添加可选字段，迁移后再设为必填；并在迁移前后验证行数。

安装量 · 447查看来源

Installation

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

技能文件

SKILL.md

最近同步 · 2026年10月15日

SKILL.md›

---
name: convex-migrate
description: "Migrate schema + backfill data on a deployed Convex app using @convex-dev/migrations."
---

<!-- GENERATED from convex-agents content/capabilities/migrate.json — do not edit by hand. -->

# Migrate the schema / data on a live app

Change a deployed schema without breaking existing data: stage the schema change, install @convex-dev/migrations, write a backfill that makes old rows valid, run it, and verify before tightening the validator.

## Workflow

1. Make the new field optional first (so deploy doesn't reject existing rows).
2. Install @convex-dev/migrations; write a migration that backfills/transforms existing rows.
3. Run the migration; verify all rows are valid.
4. Tighten the validator (make the field required) once the backfill is complete.

## Rules

- Never tighten a validator before the backfill completes — it rejects existing rows and breaks the live app.
- Add new fields as optional first, migrate, then require.
- Verify row counts before and after.