convex-migrations_skill

Overview

This skill provides practical Convex schema migration strategies for evolving production applications. It covers adding and removing fields, renaming and changing types, index management, backfilling data, and zero-downtime migration patterns. The patterns are implemented in JavaScript and emphasize safe, incremental changes and automated runners for long-running migrations.

How this skill works

The skill recommends making schema additions optional first, updating code to tolerate both old and new shapes, and running paginated internal mutations to backfill or transform existing documents. It shows how to mark and track migrations in a migrations table, schedule batch jobs with the Convex scheduler, and complete or fail migrations with explicit status updates. Indexes are added ahead of use and migrations include idempotency checks and cursored pagination to avoid downtime.

When to use it

• Adding new fields to existing tables while avoiding runtime errors
• Backfilling default values or computed fields across large datasets
• Renaming fields or changing field types with safe rollouts
• Removing deprecated fields and cleaning up legacy data
• Introducing new indexes before using them in production queries
• Coordinating long-running migrations with migration runner patterns

Best practices

• Start new fields as optional and update runtime code to handle missing values
• Backfill data in small paginated batches and schedule follow-up runs to avoid contention
• Track migration state in a migrations table to ensure idempotency and observability
• Add indexes before relying on them in queries to prevent full scans
• Use patch for incremental updates and replace to remove fields entirely when needed
• Test migration logic locally (npx convex dev) and add guards for partially migrated rows

Example use cases

• Add avatarUrl to users: deploy optional field, backfill in batches, then make it required
• Rename userName to displayName: read fallback from old field, copy values, then remove old field
• Change priority from string to numeric codes: add priorityLevel, convert in migration, update queries
• Remove legacy post field: stop using it, run a paginated replace to strip the field, then update schema
• Add a compound index for filtered queries and switch queries to use withIndex after deploy