name: convex-migrations description: Changes a live Convex schema without downtime: make a field optional, backfill in batches, flip the validator, then clean up. Uses the @convex-dev/migrations component where it fits. Use when renaming or removing a field, changing a type, splitting a table, or when deploy fails with a schema validation error on existing documents.

Convex migrations

Produces a schema change plus a batched backfill that keeps every deploy green. The one rule: the schema must describe the documents that exist right now, not the documents you want. Change the data first, then tighten the validator.

Convex has no migration files or migrate command. npx convex dev pushes the schema and validates every existing document against it. Existing data is never transformed for you.

When to reach for this

• Adding a field that should be required, but the table already has rows
• Renaming a field, changing its type, or removing it
• Splitting one table into two or merging two into one
• npx convex dev fails with Schema validation failed after a schema edit
• A backfill needs to touch more rows than one mutation can handle

For step by step recipes (rename, change type, split, merge, add required, remove) open references/migration-patterns.md. For installing and running @convex-dev/migrations open references/migrations-component.md.