migration-helper

Zero-downtime Convex schema migration requires optional-first additive updates to evolve the database while the application runs. You apply backfills via internal mutations and verify data before finalizing breaking changes.

A breaking Convex schema change includes adding required fields or changing field types. Because Convex does not auto-migrate existing data, you must use a backfill mutation to update current documents before enforcing the new schema.

To add a required field to existing Convex documents, first add it as an optional field, run an internal mutation to backfill the default value for all documents, and then update the schema to make it required.

Yes, you can use scheduled cron jobs for batch data backfills in Convex. This operational pattern allows you to process large datasets incrementally with verification checkpoints, ensuring zero-downtime during migration.

The best way to rename a Convex field is an additive data-copy migration. You add the new field, backfill it from the old field using internal mutations, update application code to dual-write, and then remove the old field.

Deleting old fields immediately risks data loss if the backfill failed or application code was not fully updated. You should use a dual-write pattern and maintain the old field until you verify the new schema is fully operational.