stripe-migration-pattern

What problem does it solve?

This Skill provides a structured pattern to perform zero-downtime migrations on Convex schema changes. It enables resumable, multi-phase migrations that minimize risk and allow rollback opportunities between phases.

Core Features & Use Cases

• Six-phase migration pattern: schema, backfill, dual-write, dual-read, cleanup, and complete, designed to migrate large datasets safely.
• Checkpoint-driven progress: track per-migration progress with checkpoint data to resume after outages.
• Cursor-based backfill: migrate data in batches without relying on offsets, ensuring scalability.
• Dual-write/dual-read strategy: migrate to new structures while maintaining compatibility and enabling safe cutovers.
• Use Case: upgrading a Convex schema in a production app with 1M+ records, minimizing downtime.

Quick Start

To begin, initialize a migration with a unique ID, configure batch sizes, and run the orchestrator to progress through phases. Monitor checkpoints and complete the migration once the final phase finishes. Then perform the cleanup phase to remove old fields.