Schema migration strategies for evolving applications including adding new fields, backfilling data, removing deprecated fields, index migrations, and zero-downtime migration patterns

Convex Migrations Evolve your Convex database schema safely with patterns for adding fields, backfilling data, removing deprecated fields, and maintaining zero downtime deployments. Documentation Sources Before implementing, do not assume; fetch the latest documentation: Primary: https://docs.convex.dev/database/schemas Schema Overview: https://docs.convex.dev/database Migration Patterns: https://stack.convex.dev/migrate data postgres to convex For broader context: https://docs.convex.dev/llms.txt Instructions Migration Philosophy Convex handles schema evolution differently than traditional databases: No explicit migration files or commands Schema changes deploy instantly with npx convex dev Existing data is not automatically transformed Use optional fields and backfill mutations for safe migrations Adding New Fields Start with optional fields, then backfill: Removing Fields Remove field usage before removing from schema: Renaming Fields Renaming requires copying data to new field, then removing old: Adding Indexes Add indexes before using them in queries: Changing Field Types Type changes require careful migration: Migration Runner Pattern Create a reusable migration system: Examples Schema with Migration Support Best Practices Never run npx convex deploy unless explicitly instructed Never run any git commands unless explicitly instructed Always start with optional fields when adding new data Backfill data in batches to avoid timeouts Test migrations on development before production Keep track of completed migrations to avoid re running Update code to handle both old and new data during transition Remove deprecated fields only after all code stops using them Use pagination for large datasets Add appropriate indexes before running queries on new fields Common Pitfalls 1. Making new fields required immediately Breaks existing documents 2. Not handling undefined values Causes runtime errors 3. Large batch sizes Causes function timeouts 4. Forgetting to update indexes Queries fail or perform poorly 5. Running migrations without tracking May run multiple times 6. Removing fields before code update Breaks existing functionality 7. Not testing on development Production data issues References Convex Documentation: https://docs.convex.dev/ Convex LLMs.txt: https://docs.convex.dev/llms.txt Schemas: https://docs.convex.dev/database/schemas Database Overview: https://docs.convex.dev/database Migration Patterns: https://stack.convex.dev/migrate data postgres to convex

convex-migrations