About convex-migrate
convex-migrate is a skill for changing schemas in deployed Convex apps while preserving existing data. It guides developers through staged schema updates, backfills, and validation checks.
Key features
- 01Optional-first schema changes
- 02Backfill and transform existing rows
- 03Verify row counts before and after
- 04Tighten validators after migration
Use cases
- 01Adding a required field to deployed records
- 02Updating existing data for a schema change
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