stripe-migration-pattern

Zero-downtime Convex schema migrations require a resumable six-phase pattern: schema, backfill, dual-write, dual-read, cleanup, and complete. This approach uses checkpoint tracking and cursor-based batches to ensure data integrity during complex evolutions.

The dual-write and dual-read strategy allows you to migrate to new schema structures while maintaining compatibility. It enables safe cutovers by writing and reading from both old and new data formats simultaneously before finalizing the cleanup phase.

You can resume a Convex migration after an outage by using checkpoint-driven progress. The migration pattern tracks per-migration progress with checkpoint data, allowing the orchestrator to pick up exactly where it left off without restarting.

You backfill large Convex datasets using a cursor-based approach instead of offsets. This method migrates data in sequential batches, ensuring scalability and preventing performance degradation on production applications with over a million records.

To safely remove old fields after a Convex schema upgrade, execute the cleanup phase after dual-read and dual-write verification succeed. This final phase removes deprecated structures once the new schema is fully operational and verified.