migration-helper

SKILL.md

Plan and execute Convex schema migrations safely with zero-downtime data transformations.

Covers safe additive changes (optional fields, new tables, indexes) that require no migration code, and breaking changes (required fields, type changes, renames) that need custom migration functions

Provides patterns for batch processing, scheduled migrations via cron jobs, and dual-write strategies to maintain app availability during transitions

Includes complete examples for common scenarios: adding required fields, changing field types, renaming fields, and migrating from nested to relational data structures

Offers a migration checklist and verification queries to confirm all records have been successfully transformed before removing old schema fields

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

No Automatic Migrations: Convex doesn't automatically migrate data

Additive Changes are Safe: Adding optional fields or new tables is safe

Breaking Changes Need Code: Required fields, type changes need migration code

Zero-Downtime: Write migrations to keep app running during migration