convex-migration-helper

The convex-migration-helper skill is designed to streamline and safely execute schema and data migrations within Convex applications. It provides an easy-to-follow process for managing breaking changes to the database schema, ensuring smooth transitions even when the changes are complex. By utilizing the widen-migrate-narrow workflow, this skill prevents disruptions in the application, offering a reliable approach to backfilling documents, modifying field types, and managing table structures. The skill addresses the inherent challenges posed by schema validation constraints in Convex, such as adding required fields, changing field types, or deleting fields, all of which are common migration pain points in evolving systems.

Key capabilities include running migrations online with zero downtime, where the app continues to serve requests during data updates. The skill prioritizes safe migrations by recommending new field additions rather than altering existing field types and emphasizes data preservation by advocating the deprecation of fields instead of deletion. By leveraging the @convex-dev/migrations component, the skill supports automated batching, progress monitoring, and resuming migrations from failures, making it a robust solution for handling complex migrations with minimal risk. It is intended for developers working with Convex who need to execute migrations for schema evolution, including tasks such as adding required fields, merging or splitting tables, and transforming existing data structures.

This skill is best suited for developers managing applications that rely on Convex as their backend, especially when those applications require complex data transformations or schema updates. It provides a reliable workflow for safely migrating large datasets and adapting to evolving schema requirements without risking downtime or data loss. Use this skill when dealing with breaking changes, multi-deploy rollouts, or data transformation tasks on existing Convex tables.