From get-convex-agent-skills-2
Plans Convex schema and data migrations using widen-migrate-narrow and @convex-dev/migrations for breaking changes, backfills, table reshaping, and zero-downtime rollouts.
npx claudepluginhub joshuarweaver/cascade-code-general-misc-3 --plugin get-convex-agent-skills-2This skill uses the workspace's default tool permissions.
Safely migrate Convex schemas and data when making breaking changes.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Checks Next.js compilation errors using a running Turbopack dev server after code edits. Fixes actionable issues before reporting complete. Replaces `next build`.
Safely migrate Convex schemas and data when making breaking changes.
Convex will not let you deploy a schema that does not match the data at rest. This is the fundamental constraint that shapes every migration:
This means migrations follow a predictable pattern: widen the schema, migrate the data, narrow the schema.
Convex migrations run online, meaning the app continues serving requests while data is updated asynchronously in batches. During the migration window, your code must handle both old and new data formats.
When changing the shape of data, create a new field rather than modifying an existing one. This makes the transition safer and easier to roll back.
Unless you are certain, prefer deprecating fields over deleting them. Mark the field as v.optional and add a code comment explaining it is deprecated and why it existed.
// Before
users: defineTable({
name: v.string(),
});
// After - safe, new field is optional
users: defineTable({
name: v.string(),
bio: v.optional(v.string()),
});
posts: defineTable({
userId: v.id("users"),
title: v.string(),
}).index("by_user", ["userId"]);
users: defineTable({
name: v.string(),
email: v.string(),
}).index("by_email", ["email"]);
Every breaking migration follows the same multi-deploy pattern:
Deploy 1 - Widen the schema:
Between deploys - Migrate data:
Deploy 2 - Narrow the schema:
For any non-trivial migration, use the @convex-dev/migrations component. It handles batching, cursor-based pagination, state tracking, resume from failure, dry runs, and progress monitoring.
See references/migrations-component.md for installation, setup, defining and running migrations, dry runs, status monitoring, and configuration options.
See references/migration-patterns.md for complete patterns with code examples covering:
.collect() on large tables: Hits transaction limits or causes timeouts. Use the migrations component for proper batched pagination. .collect() is only safe for tables you know are small.dryRun: true to validate migration logic before committing changes to production data. Catches bugs before they touch real documents.v.optional and a comment. Only delete after you are confident the data is no longer needed and no code references it.@convex-dev/migrations componentdryRun: true