convex-migrate
get-convex/agent-skills
Safely migrate schema and backfill data on live Convex apps without downtime.
What is convex-migrate?
Migrate deployed Convex schemas and backfill existing data using @convex-dev/migrations. Use this when you need to change your data model on a live app without breaking existing rows or causing downtime.
- Stage schema changes by making new fields optional first
- Write and run migrations to backfill or transform existing rows
- Verify data integrity before tightening validators
- Prevent validator rejections that would break live apps
- Transform old rows to match new schema requirements
How to install convex-migrate
npx skills add https://github.com/get-convex/agent-skills --skill convex-migrate- Existing Convex project and deployed app
- @convex-dev/migrations package installed
How to use convex-migrate
- 1.Make the new field optional in your schema
- 2.Install @convex-dev/migrations in your Convex project
- 3.Write a migration function that backfills or transforms existing rows
- 4.Run the migration and verify row counts match before and after
- 5.Tighten the validator (make the field required) once backfill completes
- 6.Deploy the updated schema
Use cases
- Adding a required field to an existing table with millions of rows
- Renaming or restructuring fields across your database
- Changing field types while preserving existing data
- Backfilling computed or derived values for historical records
- Gradually rolling out schema changes to production
- Backend engineers managing Convex databases
- Full-stack developers deploying schema changes to production
- Teams running live applications that cannot afford downtime
convex-migrate FAQ
The validator will reject existing rows that don't match the new schema, breaking your live app. Always backfill first, then tighten.
Yes, that's the purpose. The staged approach (optional → migrate → require) ensures zero downtime.
Compare row counts before and after the migration, and check that all rows now satisfy the new validator.
Write the migration function to handle your specific transformation logic; @convex-dev/migrations runs it against all existing rows.
Full instructions (SKILL.md)
Source of truth, from get-convex/agent-skills.
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
- 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.
Related skills
More from get-convex/agent-skills and the wider catalog.
convex-migrate-rehearse
Rehearse schema changes on a preview deployment before promoting to production with snapshot rollback.
convex-migration-helper
Plan and execute safe Convex schema migrations with widen-migrate-narrow pattern and batched data backfills.
convex-monitor
Watch for the next error or request in a Convex app and react to it in real-time.
convex-optimize
Audit and optimize Convex apps with security, scale, and observability improvements.
convex-performance-audit
Diagnose and fix Convex performance issues: reads, subscriptions, write contention, and function limits.
convex-quickstart
Scaffold a Next.js + Convex app from a one-sentence idea and run it locally in seconds.