convex-migration-helper

Plans and executes Convex schema and data migrations using widen-migrate-narrow workflows.

Updated Aug 12, 2026
One-click install
npx skills add https://github.com/JuanQuenga/statsconnect --skill convex-migration-helper-juanquenga
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: convex-migration-helper
Source: https://github.com/JuanQuenga/statsconnect/tree/main/apps/clashcrown/.agents/skills/convex-migration-helper
Command: npx skills add https://github.com/JuanQuenga/statsconnect --skill convex-migration-helper-juanquenga

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @convex-dev/migrations, and includes references (resource) components.

What problem does it solve? Breaking schema changes in Convex cannot deploy while existing data violates the new schema, so developers need a safe multi-deploy process to backfill and reshape production data without downtime. ## Core Features & Use Cases - Widen-Migrate-Narrow Workflow: Guides the multi-deploy pattern of widening the schema, backfilling data with the @convex-dev/migrations component, then narrowing the schema. - Migration Pattern Library: Provides reference implementations for adding required fields, changing field types, splitting nested data into tables, deleting fields, and cleaning orphaned documents. - Zero-Downtime Strategies: Covers dual-write and dual-read approaches plus dry runs, batching, resume-from-failure, and migration verification queries. - Use Case: When renaming a boolean field like isPro to an enum plan on a production teams table, use this Skill to plan the deploys, write the batched migration, dry-run it, and verify completion before narrowing the schema. ## Quick Start Ask the assistant to plan a safe Convex migration for your schema change, describing the current field shape and the target shape so it can produce the widen-migrate-narrow deploy plan.

Frequently Asked Questions about convex-migration-helper

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a required field to an existing Convex table?▼

Add the field as optional first, deploy code that writes it for new documents, then run a migration with @convex-dev/migrations to backfill existing documents. After verifying all documents are migrated, deploy a final schema making the field required.

How do I run a Convex data migration in production?▼

Define the migration with migrations.define from @convex-dev/migrations, test it with a dry run using npx convex run migrations:myMigration '{"dryRun": true}', then run it with npx convex run migrations:myMigration --prod and monitor status.

Why does Convex reject my schema deploy after changing a field type?▼

Convex validates that existing data matches the schema, so changing a field type fails when documents still hold the old type. Widen the schema to accept both formats, migrate the data, then narrow the schema in a later deploy.

When should I avoid using the Convex migrations component?▼

Skip it for greenfield schemas, optional fields needing no backfill, new tables, or index-only changes. For small tables of a few thousand documents, a single internalMutation with .collect() is sufficient.

Can I change a Convex field type without downtime?▼

Yes, using dual write or dual read strategies. Dual write writes both old and new formats while reading the old one until migration completes; dual read reads both formats while writing only the new one.