Convex migrations

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.

The safe sequence

Every migration follows the same six steps. Skipping one is how deploys break.

1. Make the field optional in convex/schema.ts (or add the new field as v.optional).
2. Deploy with npx convex dev. Update readers to handle undefined and writers to set the new shape.
3. Backfill existing documents in batches with an internal mutation or the migrations component.
4. Flip the validator to its final shape (v.string() instead of v.optional(v.string()), or drop the old field).
5. Deploy again. Validation now passes because every document already matches.
6. Clean up: delete fallback code, remove the backfill function, drop stale indexes.

Steps 1 and 2 must ship before step 3 starts. Otherwise new writes keep producing old shaped documents while the backfill runs.

Hand rolled batched backfill

One internalMutation that pages through the table with paginate, patches only documents that still need it, then reschedules itself with the continue cursor. Each batch is its own transaction, so a large table never hits the per function limit.

// convex/migrations.ts
import { internalMutation } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";

const BATCH_SIZE = 100;