convex-migration-helper

To safely execute breaking schema migrations in Convex, use the widen-migrate-narrow pattern to widen the schema, backfill data, and narrow the schema without service interruption. This prevents data loss during production deployments.

The best way to rename or change a field type in a production Convex database is applying a structured multi-step workflow. You temporarily widen the schema to support both formats, migrate the data, and then narrow the schema to enforce the new definition.

Yes, the Convex migration workflow supports batching, state tracking, and resume-from-failure capabilities by integrating with the @convex-dev/migrations component. This allows you to execute dry runs and monitor progress during complex data backfills.

To add a required field to an existing Convex table without downtime, follow the widen-migrate-narrow workflow. You first make the field optional, backfill the required data for all existing records, and finally narrow the schema to make the field mandatory.

You need the widen-migrate-narrow pattern for Convex deployments when making breaking schema changes like table reshaping or type changes. It mitigates deployment failure risks by ensuring both old and new formats are temporarily supported during data transition.