convex-migration-helper

To safely add a required field in Convex, use the widen-migrate-narrow workflow to add the field optionally, backfill existing data, and then narrow the schema to enforce it.

The widen-migrate-narrow workflow is a process for Convex data migrations where you widen schema flexibility, backfill data, and narrow constraints to execute breaking changes with minimal downtime.

Yes, executing the planned Convex schema and data migrations requires the @convex-dev/migrations package to handle data backfilling and schema narrowing.

To backfill data when adding a new required field to a Convex table, plan a data migration that populates the new field for existing records before narrowing the schema to enforce it.

The best way to handle breaking schema changes in Convex is following the widen-migrate-narrow workflow, which separates schema widening, data backfilling, and schema narrowing into safe steps.