convex-migration-helper

Convex schema migrations use a widen-migrate-narrow strategy to achieve zero downtime. You first make schema fields compatible, backfill existing documents via batched resumable migrations, then tighten the schema validation.

Adding a required field breaks Convex deployments because existing data at rest fails schema validation. You must widen the schema first, backfill all existing documents with the new field, then narrow the schema to enforce the required constraint.

The best way to rename or delete a Convex field is using an online migration pattern with dual-read and dual-write handling. This accounts for documents created during the migration window, ensuring data integrity before removing the old field.

Yes, you can use the @convex-dev/migrations component for batched and resumable backfills. It provides operational guardrails to verify completion via status checks when applying schema changes in production or dev environments.

Migrating nested data to relational tables in Convex requires splitting table structures using a planned widen-migrate-narrow workflow. You extract nested data into a new table, backfill relational references, and update application logic before narrowing.

You should avoid making schema fields required in Convex until after all existing documents are backfilled. Tightening the schema prematurely will cause validation errors for data at rest that lacks the new required field.