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 run 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.

Using .collect() is only safe for small tables of a few thousand documents in a single internalMutation. Larger tables hit transaction limits or timeouts, so use the @convex-dev/migrations component for batched, resumable processing.

No migration is needed for adding optional fields, adding new tables, or adding indexes, since these do not conflict with existing data. Greenfield schemas with no production data also require no migration.