convex-migration-helper

A widen-migrate-narrow workflow handles breaking Convex schema changes by widening the schema first, running a backfill migration, then narrowing the schema once all documents are updated.

Adding a required field to a Convex table requires widening the schema first to make the field optional, running a backfill migration to populate all existing documents, and finally narrowing the schema to enforce the required constraint.

The @convex-dev/migrations workflow handles large data backfills through batched, resumable execution with dry runs. It includes a verification step to ensure all documents are migrated before completing the process.

Making a Convex field required too early breaks deployments because schema validation rejects existing documents that lack the new field, blocking deployment until all data is updated through a prior migration backfill.

Renaming or deleting fields in a Convex schema requires an online migration strategy that handles both old and new data formats during the migration window, ensuring existing queries continue functioning until the final schema narrowing.

You need a dual format online migration for Convex when applying breaking changes like changing field shapes, splitting or merging tables, or renaming fields, where both old and new data formats must coexist during the transition.