convex-migration-helper

Add the field as optional first and deploy, then run a migration with @convex-dev/migrations to backfill existing documents, and finally deploy a narrowed schema making the field required. Convex rejects deploys where existing documents lack a required field, so the widen-migrate-narrow sequence is mandatory.

Create a new field with the target type rather than modifying the existing one, then use dual-write or dual-read strategies during the migration window. Backfill old documents with the migrations component, verify completion, and remove the old field in a final deploy.

Convex validates the schema against data at rest, so deploys fail when existing documents do not match, such as missing a newly required field or holding an old field type. Widen the schema to accept both formats, migrate the data, then narrow the schema.

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

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 real documents.

No migration is needed for greenfield schemas with no existing data, adding optional fields without backfilling, adding new empty tables, or adding and removing indexes. These changes deploy directly without the widen-migrate-narrow workflow.