convex-migrations

Manage Convex database schema migrations with backfill mutations and zero-downtime patterns.

Updated Mar 7, 2026
One-click install
npx skills add https://github.com/pratikpakhale/convex-next-starter --skill convex-migrations-pratikpakhale
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: convex-migrations
Source: https://github.com/pratikpakhale/convex-next-starter/tree/main/.agent/skills/convex/modules/convex-migrations
Command: npx skills add https://github.com/pratikpakhale/convex-next-starter --skill convex-migrations-pratikpakhale

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill provides robust strategies and patterns for managing schema changes in Convex databases, ensuring data integrity and minimizing downtime during application evolution.

Core Features & Use Cases

  • Schema Evolution: Safely add, remove, or rename fields in your Convex tables.
  • Data Backfilling: Implement mutations to populate new fields with existing data.
  • Zero-Downtime Migrations: Apply schema changes without interrupting service.
  • Index Management: Add and utilize new indexes for improved query performance.
  • Use Case: You need to add a new avatarUrl field to your users table. This Skill guides you through making the field optional, backfilling existing users with default avatars, and then making the field required.

Quick Start

Use the convex-migrations skill to add a new optional 'avatarUrl' field to the 'users' table, then backfill existing users with default avatars.

Frequently Asked Questions about convex-migrations

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

FAQPage Schema
How do I add a new required field to a Convex database schema without downtime?

To add a required field to a Convex database without downtime, first define it as optional, run a backfill mutation to populate existing records with default values, and then enforce it as required. This schema migration strategy ensures data integrity during evolution.

What is the best way to backfill data in Convex tables after a schema change?

The best way to backfill data in Convex tables is by implementing dedicated backfill mutations. These mutations safely populate newly added optional fields with default values or computed data for existing records before making the fields required.

Can I safely remove or rename deprecated fields in a Convex schema?

Yes, you can safely remove or rename deprecated fields in a Convex schema by following zero-downtime migration patterns. This involves incrementally updating your schema evolution strategy to ensure application stability and prevent data loss.

Does Convex support zero-downtime migrations for changing field types?

Convex supports zero-downtime migrations for safe field type changes by utilizing optional fields and backfilling data. This approach allows you to apply schema changes without interrupting active service or corrupting existing data.

When do I need to manage indexes during Convex database migrations?

You need to manage indexes during Convex database migrations when adding new fields that require improved query performance. Safely adding and utilizing new indexes ensures your queries remain efficient as your schema evolves.