convex-migration-helper

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

Define the migration with migrations.define and run it directly from the CLI using npx convex run migrations:myMigration --prod. Test first with dryRun: true, then monitor progress with npx convex run --component migrations lib:getStatus --watch.

Adding optional fields, adding new tables, and adding indexes are safe changes that deploy directly without migrating data. Migrations are only needed for breaking changes like required fields, type changes, renames, or deletions on tables with existing data.

Convex validates the schema against data at rest and rejects the deploy if existing documents lack the required field. Widen the schema to make the field optional, backfill all documents with a migration, then narrow the schema in a later deploy.

Only for small tables of a few thousand documents, since .collect() hits transaction limits or timeouts on large tables. For anything larger, use the @convex-dev/migrations component, which handles batched cursor-based pagination and resume from failure.

Use dual write, where code writes both old and new formats while reading the old format until migration completes, or dual read, where code reads both formats preferring the new one while writing only the new format. Dual write is preferred because rollback stays safe.