convex-migration-helper
Installation
Summary
Plan and execute Convex schema migrations safely with multi-deploy workflows and data transformation.
- Follows a predictable three-step pattern: widen schema, migrate data, narrow schema; handles online migrations where the app continues serving requests during async data updates
- Provides the
@convex-dev/migrationscomponent for batched, cursor-based pagination with state tracking, dry-run testing, progress monitoring, and automatic resume from failure - Covers common patterns including adding required fields, deleting fields, changing field types, splitting nested data, and cleaning up orphaned documents
- Supports dual-write and dual-read strategies for zero-downtime migrations; includes a small-table shortcut for direct in-mutation backfills on tables under a few thousand documents
SKILL.md
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 or deleting fields
- Migrating from nested to relational data
When Not to Use
- Greenfield schema with no existing data in production or dev
- Adding optional fields that do not need backfilling
- Adding new tables with no existing data to migrate
- Adding or removing indexes with no correctness concern
- Questions about Convex schema design without a migration need
Related skills
More from get-convex/agent-skills
convex-quickstart
Creates or adds Convex to an app. Use for new Convex projects, npm create
44.8Kconvex-performance-audit
Audits Convex performance for reads, subscriptions, write contention, and
44.3Kconvex-setup-auth
Sets up Convex auth, identity mapping, and access control. Use for login, auth
44.2Kconvex-create-component
Builds reusable Convex components with isolated tables and app-facing APIs.
44.1Kconvex
Routes general Convex requests to the right project skill. Use when the user
20.7Kconvex-helpers-guide
Discover and use convex-helpers utilities for relationships, filtering, sessions, custom functions, and more. Use when you need pre-built Convex patterns.
572