convex-migrations

Migrate Convex schemas with optional fields, backfills, and index changes.

Updated Feb 8, 2026

Search Tags:#versioning #schema #migration #zero-downtime #convex #backfill #data-migration

Ready to run

npx skills add https://github.com/gursheyss/styx --skill convex-migrations-gursheyss

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: convex-migrations
Source: https://github.com/gursheyss/styx/tree/main/.agents/skills/convex-migrations
Command: npx skills add https://github.com/gursheyss/styx --skill convex-migrations-gursheyss

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve?

Convex schema migrations are inherently risky and can cause downtime when evolving applications. This Skill provides structured strategies for schema evolution, including adding new fields, backfilling data, removing deprecated fields, index migrations, and zero-downtime deployment patterns.

Core Features & Use Cases

Stepwise migration patterns: add optional fields, backfill data, then promote to required.
Backfill orchestration and progress tracking to handle large datasets with batching.
Guidelines for renames, removals, type changes, and index migrations with safe production practices.

Quick Start

Execute the migration guide to add a new field, backfill existing data, and transition to the new schema.

Frequently Asked Questions about convex-migrations

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

FAQPage Schema

How do I perform zero-downtime schema migrations in Convex?▼

Zero-downtime Convex schema migrations are achieved by evolving tables with optional fields, running backfills, and updating indexes before removing deprecated fields. This enforces a stepwise workflow where code paths switch safely without deployment interruptions.

What is the best way to backfill large datasets during a Convex migration?▼

Backfilling large Convex datasets requires orchestrated batch mutations and progress tracking to safely update existing records. This approach ensures data migrations complete iteratively without overloading the database or causing downtime during the schema transition.

How do I safely rename or remove fields in a Convex schema?▼

Renaming or removing fields in a Convex schema requires introducing the new field, backfilling data, and switching code paths before deletion. The deprecated field must only be removed after all application code successfully transitions to the new schema.

Can I change indexes and table schemas without downtime in Convex?▼

Yes, Convex index migrations and table schema changes can be applied without downtime by following stepwise patterns. You introduce index changes alongside optional fields, ensuring existing queries remain functional while the new schema is deployed.

When should I use a stepwise migration pattern for Convex databases?▼

You should use a stepwise Convex migration pattern when adding, removing, or renaming fields and performing data migrations across large datasets. It prevents downtime by separating code deployments from schema changes and backfill operations.