convex-migration-helper

Add the field as optional first, deploy code that writes it for new documents, then backfill existing documents with a migration using @convex-dev/migrations. After verifying all documents are migrated, deploy a final schema that makes the field required.

Use the widen-migrate-narrow pattern: widen the schema to accept both formats, run an online batched migration, then narrow the schema. During the window, use dual write (write both formats, read old) or dual read (read both, write new) so the app keeps serving requests.

Convex rejects deploys when the schema does not match data at rest, such as adding a required field that existing documents lack or changing a field type. Widen the schema to allow both formats and migrate the data before narrowing.

Only for small tables of a few thousand documents, via a single internalMutation. Larger tables hit transaction limits or timeouts, so use the @convex-dev/migrations component which handles batched pagination, resume from failure, and progress tracking.

Run the migration with dryRun set to true, for example npx convex run migrations:runIt '{"dryRun": true}'. This executes one batch and rolls back, letting you validate the migration logic without changing any documents.

Skip migrations for greenfield schemas with no existing data, adding optional fields that need no backfill, adding new empty tables, or adding indexes. These changes deploy safely without touching existing documents.