convex-migration-helper

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

Define the migration with migrations.define from @convex-dev/migrations, test it with a dry run using npx convex run migrations:myMigration '{"dryRun": true}', then execute it with npx convex run migrations:myMigration --prod and monitor status.

Convex validates that the schema matches data at rest, so it rejects deploys where existing documents violate the new schema, such as missing a newly required field. Widen the schema to accept both formats, migrate the data, then narrow the schema.

Skip it for greenfield schemas, adding optional fields, new tables, or index changes with no data impact. For small tables of a few thousand documents, a single internalMutation using .collect() is sufficient.

Use dual write, where code writes both old and new formats while reading the old format until migration completes, allowing safe rollback. Alternatively use dual read, reading both formats while writing only the new one.