convex-migration-helper

Split or merge Convex tables by applying the widen-migrate-narrow workflow to support both schemas simultaneously, backfilling existing documents into the new structure, verifying completion, and then narrowing the schema to remove the legacy table.

To add a required field to a Convex table, widen the schema to make the field optional, deploy code that dual-writes the new field while dual-reading both formats, backfill existing documents with a default value, then narrow the schema to make it required.

The best way to rename a Convex database field is the widen-migrate-narrow pattern: add the new field to the schema, deploy code that dual-writes both fields, run a migration job to backfill the new field from the old one, then narrow the schema to drop the old field.

When running Convex data migrations, avoid missed documents and transaction limits by using cursored pagination and batched processing via the @convex-dev/migrations component, which tracks migration state and supports resumable execution for large datasets.

Yes, the @convex-dev/migrations component supports dry-run functionality to preview changes and resume capabilities through state tracking, enabling safe batched online migrations with cursored pagination to handle large datasets without exceeding transaction limits.