Skip to content

convex-migrate

Migrate schema + backfill data on a deployed Convex app using @convex-dev/migrations.

35,745
installs
0 up / 0 down, score 0.00
votes
66
repo stars
Updated
less than a month ago
In the catalog since
16 Oct 2026
From
convex/agent-skills
Other
Get it through your agent npx skills add convex/agent-skills@convex-migrate

Skill instructions

Rendered from the published SKILL.md, 19 lines.

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.