convex-migrations

Orchestrate zero-downtime Convex schema migrations and data backfills with progress tracking.

Updated Feb 1, 2026

Search Tags:#database #migrations #schema #zero-downtime #data-modeling #convex #backfill

Ready to run

npx skills add https://github.com/EricJamesCrow/smartpockets --skill convex-migrations-ericjamescrow

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: convex-migrations
Source: https://github.com/EricJamesCrow/smartpockets/tree/main/.claude/skills/convex-migrations
Command: npx skills add https://github.com/EricJamesCrow/smartpockets --skill convex-migrations-ericjamescrow

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Convex schema migrations historically risk downtime and data inconsistencies. This Skill provides patterns and tooling to evolve schemas safely, backfill existing data, and track migration progress so applications can evolve without service interruption.

Core Features & Use Cases

Migration runner with start, update, complete, and fail semantics to coordinate long-running changes.
Backfill strategies for optional-to-required field transitions, type changes, and data normalization across large datasets.
Index migrations and safe deprecation/renaming workflows with code changes kept in sync.

Quick Start

Start the migration process to backfill missing timestamps across users and monitor progress via the migrations tracker.

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 require a migration runner pattern with optional fields, backfill mutations, and safe batching to evolve schemas without service interruption. This approach tracks progress using start, update, complete, and fail semantics.

What is the best way to backfill data when changing field types in a Convex database?▼

Backfilling data for field type changes in a Convex database involves running batched backfill mutations that normalize existing records while preserving backward compatibility. A migration runner coordinates this process and tracks progress across large datasets.

Can I rename fields or add indexes across large datasets without downtime in Convex?▼

Yes, you can rename fields or add indexes across large Convex datasets without downtime by using safe batching and index deprecation workflows. Code changes must read from new fields while preserving backward compatibility during the transition.

How do I transition an optional field to required in Convex without breaking existing queries?▼

Transitioning an optional field to required in Convex requires backfilling missing values across existing records first. The migration runner applies safe batched mutations to populate data before enforcing the required schema constraint.

What limitations exist when running Convex data backfills on large datasets?▼

Convex data backfills on large datasets require safe batching to avoid timeouts and must preserve backward compatibility by keeping old fields readable during the migration. Progress tracking ensures long-running changes complete without data inconsistencies.