// Plan and execute Convex schema migrations safely, including adding fields, creating tables, and data transformations. Use when schema changes affect existing data.
Integrate and maintain Robelest Convex Auth in apps by always checking upstream before implementation. Use when adding auth setup, updating auth wiring, migrating between upstream patterns, or troubleshooting @robelest/convex-auth behavior across projects.
Initialize a new Convex project from scratch or add Convex to an existing app. Use when starting a new project with Convex, scaffolding a Convex app, or integrating Convex into an existing frontend.
Set up Convex authentication with proper user management, identity mapping, and access control patterns. Use when implementing auth flows, setting up OAuth providers, or adding role-based access control.
Full-stack Convex development guidelines covering React, Vite, TypeScript, mutations, auth, design system, and documentation practices. Use when building features, writing Convex functions, or making code changes in this project.
Create Convex queries, mutations, and actions with proper validation, authentication, and error handling. Use when implementing new API endpoints.
Critical Git safety rules to prevent destructive operations. Use whenever performing git operations, reverting changes, or managing commits. Prevents accidental loss of work.
| name | migration-helper |
| description | Plan and execute Convex schema migrations safely, including adding fields, creating tables, and data transformations. Use when schema changes affect existing data. |
Safely migrate Convex schemas and data when making breaking changes.
Solution: Add as optional first, backfill data, then make required.
// Step 1: Add as optional
users: defineTable({
name: v.string(),
email: v.optional(v.string()),
})
// Step 2: Create migration
export const backfillEmails = internalMutation({
args: {},
handler: async (ctx) => {
const users = await ctx.db.query("users").collect();
for (const user of users) {
if (!user.email) {
await ctx.db.patch(user._id, {
email: `user-${user._id}@example.com`,
});
}
}
},
});
// Step 3: Run migration via dashboard or CLI
// npx convex run migrations:backfillEmails
// Step 4: Make field required (after all data migrated)
users: defineTable({
name: v.string(),
email: v.string(),
})
// Step 1: Add new field (optional)
// Step 2: Copy data with internalMutation
// Step 3: Update schema (remove old field)
// Step 4: Update all code to use new field name
For large tables, process in batches:
export const migrateBatch = internalMutation({
args: {
cursor: v.optional(v.string()),
batchSize: v.number(),
},
handler: async (ctx, args) => {
const items = await ctx.db.query("largeTable").take(args.batchSize);
for (const item of items) {
await ctx.db.patch(item._id, { /* migration logic */ });
}
return {
processed: items.length,
hasMore: items.length === args.batchSize,
};
},
});
For zero-downtime migrations, write to both old and new structure during transition.
Use cron jobs for gradual migration:
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";
const crons = cronJobs();
crons.interval(
"migrate-batch",
{ minutes: 5 },
internal.migrations.migrateBatch,
{ batchSize: 100 }
);
export default crons;