Back to Details

convex-migrate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- GENERATED from convex-agents content/capabilities/migrate.json — do not edit by hand. -->
<!-- 由convex-agents的content/capabilities/migrate.json生成 — 请勿手动编辑。 -->

Migrate the schema / data on a live app

为线上应用迁移Schema/数据

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.
在不破坏现有数据的前提下修改已部署的Schema：分阶段进行Schema变更，安装@convex-dev/migrations，编写可使旧数据行生效的回填脚本，运行脚本并验证，之后再严格化校验规则。

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.
  1. 先将新字段设为可选（这样部署时不会拒绝现有数据行）。
  2. 安装@convex-dev/migrations；编写用于回填/转换现有数据行的迁移脚本。
  3. 运行迁移脚本；验证所有数据行均有效。
  4. 回填完成后，严格化校验规则（将字段设为必填）。

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.
  • 绝对不要在回填完成前严格化校验规则——这会拒绝现有数据行并导致线上应用崩溃。
  • 新增字段时先设为可选，完成迁移后再设为必填。
  • 迁移前后需验证数据行数量。