convex-migration-helper

Zero-downtime Convex schema migration uses the widen-migrate-narrow pattern to transition data safely. It enforces dual-write and dual-read strategies to keep deployments intact while applying breaking schema changes.

The widen-migrate-narrow pattern is a structured workflow for safe data migration. You first widen the schema to accept both old and new shapes, migrate existing data via backfill, then narrow the schema to enforce the new structure.

To backfill data in Convex after table reshaping, use the @convex-dev/migrations package to execute a planned data transition. This ensures existing records remain intact during restructuring without causing deployment downtime.

The @convex-dev/migrations package supports a structured workflow with validation and dry runs for Convex migrations. This allows you to verify data transitions and breaking schema changes before executing a full zero-downtime rollout.

The best way to handle breaking schema changes in Convex is applying an online migration pattern. Use the widen-migrate-narrow strategy to transition safely, ensuring existing data remains intact and deployments avoid downtime.