Plans and executes safe Convex schema and data migrations using the widen-migrate-narrow workflow and the @convex-dev/migrations component. Use this skill when a deployment fails schema validation, existing documents need backfilling, fields need adding or removing or changing type, tables need splitting or merging, or a zero-downtime migration strategy is needed. Also use when the user mentions breaking schema changes, multi-deploy rollouts, or data transformations on existing Convex tables.
Safely migrate Convex schemas and data when making breaking changes.
Convex will not let you deploy a schema that does not match the data at rest. This is the fundamental constraint that shapes every migration:
This means migrations follow a predictable pattern: widen the schema, migrate the data, narrow the schema.
Convex migrations run online, meaning the app continues serving requests while data is updated asynchronously in batches. During the migration window, your code must handle both old and new data formats.
When changing the shape of data, create a new field rather than modifying an existing one. This makes the transition safer and easier to roll back.
Unless you are certain, prefer deprecating fields over deleting them. Mark the field as v.optional and add a code comment explaining it is deprecated and why it existed.
// Before