convex-migrations

Design staged Convex schema migrations with batch backfills and fallback handling.

1|Updated Oct 10, 2025

Search Tags:#migrations #schema #indexes #zero-downtime #convex #backfill

Ready to run

npx skills add https://github.com/cgRGM/rivercitymd --skill convex-migrations-cgrgm

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: convex-migrations
Source: https://github.com/cgRGM/rivercitymd/tree/main/.cursor/skills/convex-migrations
Command: npx skills add https://github.com/cgRGM/rivercitymd --skill convex-migrations-cgrgm

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you evolve Convex schemas and data safely without breaking production documents, especially when new fields, renamed fields, removed fields, or index changes must coexist with live traffic.

Core Features & Use Cases

Safe Field Additions: Introduce optional fields first, then backfill existing records before making them required.
Data Backfills and Cleanup: Migrate old values, remove deprecated fields, and keep queries working during the transition.
Index and Type Changes: Add indexes before using them and move between field types with fallback logic and staged rollout patterns.
Use Case: A product team can add timestamps to existing users, populate them in batches, and finalize the schema only after all records are updated.

Quick Start

Ask for a safe Convex migration plan for your schema change, including the code updates, backfill approach, and final cleanup steps.

Frequently Asked Questions about convex-migrations

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

FAQPage Schema

How do I safely add a required field to a live Convex schema?▼

To safely add a required field to a live Convex schema, introduce it as optional first, backfill existing records in batches, and finalize the schema only after all documents are updated. This staged approach prevents broken production documents during live traffic.

What is the best way to rename a field in Convex without downtime?▼

The best way to rename a field in Convex without downtime is using a staged schema migration. You add the new property, update queries with fallback logic for old and new data, backfill records, then remove the deprecated field.

Can I change a field type in Convex while queries are still running?▼

Yes, you can change a field type in Convex while queries are running by applying a staged rollout pattern. This involves moving between field types with fallback logic so old and new data coexist without breaking active queries.

How do I backfill existing Convex records when introducing indexes?▼

When introducing indexes in Convex, add the indexes before using them and backfill existing records in batches. This ensures the index is populated and queries remain functional during the transition.

When should I use a staged schema update for Convex migrations?▼

Use a staged schema update for Convex migrations when evolving application data without downtime. It is required for adding fields, backfilling records, removing deprecated fields, renaming properties, and changing field types in live apps.

How to handle fallback logic for old and new data during a Convex migration?▼

To handle fallback logic for old and new data during a Convex migration, design queries to check both the old and new property names. This fallback handling protects production deployments while batch backfills and completion checks are underway.