About convex-migrate
convex-migrate is a skill for changing schemas and data on a live Convex app without invalidating existing rows. It stages validator changes around a backfill, then checks the migrated data before requiring the new field.
Key features
- 01Stage new fields as optional
- 02Backfill and transform existing rows
- 03Verify data before tightening validators
- 04Compare row counts before and after
Use cases
- 01Add a required field to a live schema
- 02Transform existing rows during a migration
Install
Copy the command and run it in a terminal.
$
npx skills add https:/After installing, type/convex-migratein Claude Code to confirm it loaded.
Details
From the project READMEMigrate 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
- Make the new field optional first (so deploy doesn't reject existing rows).
- Install @convex-dev/migrations; write a migration that backfills/transforms existing rows.
- Run the migration; verify all rows are valid.
- 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.
Comments
Markdown supported