convex-migrate

Migrating a Convex schema from optional to required without downtime requires a three-phase approach: add the optional field, run a paginated backfill on existing rows, then enforce the field as required. This progression prevents write failures during the transition.

A three-phase schema migration pattern sequentially adds an optional field, backfills existing data in batches, and then requires the field going forward. This pattern allows live deployments to transition schemas safely while maintaining continuous read and write availability.

To backfill existing rows during a live Convex schema migration, use a paginated internal action that processes rows in batches. This approach includes safe guards and idempotent operations to ensure data consistency without overwhelming the database.

Yes, canary-based validation is supported during a Convex schema migration. The process includes a canary-watched grace window during the final phase where the field becomes required, allowing you to monitor for errors before fully enforcing the constraint in production.

Yes, the Convex schema migration workflow automatically emits an Architecture Decision Record (ADR). This document captures the details of the optional-to-required field transition, ensuring the migration rationale and steps are formally recorded for future reference.

An idempotent backfill on a Convex database requires paginated batch processing with safe guards to prevent duplicate writes. It is limited by the need for prod gating and careful canary monitoring to ensure existing rows are fully updated before enforcing the required field constraint.