convex-migrations

Automate Convex schema migrations with batched backfills and index updates.

1|1|Updated Feb 7, 2026
One-click install
npx skills add https://github.com/mauricioacp/tanstack-convex-better-auth-template --skill convex-migrations-mauricioacp
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: convex-migrations
Source: https://github.com/mauricioacp/tanstack-convex-better-auth-template/tree/main/.agents/skills/convex-migrations
Command: npx skills add https://github.com/mauricioacp/tanstack-convex-better-auth-template --skill convex-migrations-mauricioacp

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Evolves Convex schemas safely by guiding and automating field additions, backfills, removals, renames, and index changes without downtime.

Core Features & Use Cases

  • Structured migration runner patterns with startMigration, updateMigrationProgress, and completeMigration.
  • Backfill and transform data in batches to minimize timeouts.
  • Evolve schemas with optional fields before making them required.
  • Track migration status and support idempotent runs.

Quick Start

Run a migration to safely evolve your Convex schema by adding fields, backfilling data, and updating indexes in batched steps.

Frequently Asked Questions about convex-migrations

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

FAQPage Schema
How do I run zero-downtime schema migrations on Convex?

Zero-downtime schema migrations on Convex are executed using a structured migration runner that processes batched backfills, tracks progress in a migrations table, and uses helper mutations to safely add, remove, or rename fields without service interruptions.

What is the best way to backfill data in batches in Convex?

Backfilling data in batches in Convex is best handled by a migration runner pattern that processes records incrementally, minimizing timeout risks while tracking status and progress through dedicated helper mutations to ensure safe completion.

How does a Convex migration runner handle evolving data models?

A Convex migration runner handles evolving data models by applying idempotent mutations that introduce optional fields before making them required, allowing progressive backfills and index updates without breaking existing application logic.

Can I rename fields and update indexes without downtime in Convex?

Yes, you can rename fields and update indexes without downtime in Convex by utilizing a batched migration runner that tracks migration status, enabling progressive schema evolution across production environments with robust error handling.

Why do my Convex schema migrations time out during large data backfills?

Convex schema migrations time out during large data backfills because processing massive datasets in a single transaction exceeds limits; implementing batched backfills with progress tracking resolves this by processing smaller data chunks incrementally.

Do I need a migrations table to safely evolve Convex schemas?

Yes, a migrations table is needed to safely evolve Convex schemas because it tracks the lifecycle state of each operation, supporting idempotent runs, logging progress, and ensuring safe recovery from failures during production backfills.