convex-migration-helper

Use the widen-migrate-narrow pattern to execute a zero-downtime Convex schema migration: widen the schema first, backfill existing data using the @convex-dev/migrations component, then narrow the schema after validation to ensure production data remains intact throughout the rollout.

The best way to backfill Convex data after adding a required field is using the migrations.define function from the @convex-dev/migrations component, which allows you to safely populate existing records with default values before enforcing the new schema constraints.

The widen-migrate-narrow pattern for Convex table reshaping works by first expanding the schema to accept both old and new shapes, running a data backfill to migrate records to the new structure, and finally tightening the schema to reject the old shape.

Yes, the @convex-dev/migrations component supports renaming fields in Convex production environments by applying zero-downtime rollout strategies that maintain backward compatibility while data is migrated to the new field names.

Plan a rollback strategy for a Convex data migration by defining validation steps during the widen phase, ensuring the @convex-dev/migrations runner can reverse the backfill if issues arise, and keeping the old schema shape available until the final narrowing step.

Use a dedicated migration component instead of direct schema changes in Convex when handling breaking schema changes, large-scale data backfills, or table reshaping that requires zero-downtime rollouts and validation across development and production environments.