migration-helper

Convex Migration Helper

Safely migrate Convex schemas and data when making breaking changes.

When to Use

• Adding new required fields to existing tables
• Changing field types or structure
• Splitting or merging tables
• Renaming fields
• Migrating from nested to relational data

Migration Principles

1. No Automatic Migrations: Convex doesn't automatically migrate data
2. Additive Changes are Safe: Adding optional fields or new tables is safe
3. Breaking Changes Need Code: Required fields, type changes need migration code
4. Zero-Downtime: Write migrations to keep app running during migration

Safe Changes (No Migration Needed)

• Adding optional fields
• Adding new tables
• Adding indexes

Breaking Changes (Migration Required)

Adding Required Field

Solution: Add as optional first, backfill data, then make required.

// Step 1: Add as optional
users: defineTable({
  name: v.string(),
  email: v.optional(v.string()),
})

// Step 2: Create migration
export const backfillEmails = internalMutation({
  args: {},
  handler: async (ctx) => {
    const users = await ctx.db.query("users").collect();
    for (const user of users) {
      if (!user.email) {
        await ctx.db.patch(user._id, {
          email: `user-${user._id}@example.com`,
        });
      }
    }
  },
});

// Step 3: Run migration via dashboard or CLI
// npx convex run migrations:backfillEmails

// Step 4: Make field required (after all data migrated)
users: defineTable({
  name: v.string(),
  email: v.string(),
})

Renaming Field

// Step 1: Add new field (optional)
// Step 2: Copy data with internalMutation
// Step 3: Update schema (remove old field)
// Step 4: Update all code to use new field name

Migration Patterns

Batch Processing

For large tables, process in batches:

export const migrateBatch = internalMutation({
  args: {
    cursor: v.optional(v.string()),
    batchSize: v.number(),
  },
  handler: async (ctx, args) => {
    const items = await ctx.db.query("largeTable").take(args.batchSize);

    for (const item of items) {
      await ctx.db.patch(item._id, { /* migration logic */ });
    }

    return {
      processed: items.length,
      hasMore: items.length === args.batchSize,
    };
  },
});