convex-migrations

Automate Convex schema migrations with batched processing and progress tracking.

33|2|Updated Feb 21, 2025
One-click install
npx skills add https://github.com/yspreen/dotfiles --skill convex-migrations-yspreen
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: convex-migrations
Source: https://github.com/yspreen/dotfiles/tree/main/.agents/skills/convex-migrations
Command: npx skills add https://github.com/yspreen/dotfiles --skill convex-migrations-yspreen

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Schema migrations in dynamic applications are hard to coordinate safely. This skill provides proven patterns for adding fields, backfilling data, removing deprecated fields, migrating indexes, and achieving zero-downtime deployments.

Core Features & Use Cases

  • Migration philosophy: no disruptive downtime; deploys instantly with structured steps.
  • Add/rename/remove fields and backfill data with batched processing and safe fallbacks.
  • Index migrations and data-model evolution with progressive rollout and monitoring.
  • End-to-end migration runner pattern: track progress, handle failures, and ensure idempotence.

Quick Start

Start by creating a migrations table, implement a batch migration runner, and trigger it to apply changes without downtime.

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 a Convex backend?

Zero-downtime schema migrations in a Convex backend are executed through batched processing, optional fields, and a tracking table with start, update, complete, and fail mutations to apply changes without service disruption.

What is the best way to backfill data when adding new fields to a production database?

Backfilling data when adding new fields is best handled by a batch migration runner that processes records progressively, persists progress, and maintains safe fallbacks to ensure robust rollback capabilities if failures occur.

Can I migrate indexes and evolve data models without taking my application offline?

Yes, you can migrate indexes and evolve data models without downtime by applying progressive rollout patterns with continuous monitoring, ensuring index changes deploy instantly alongside active production traffic.

How do I handle migration failures and ensure idempotence during schema evolution?

Migration failures during schema evolution are handled using an end-to-end runner pattern that tracks progress, triggers fail mutations, and ensures idempotence so batched processing can safely resume or rollback without data corruption.

Do I need a tracking table to manage batched schema changes in Convex?

Yes, a migrations tracking table is required to manage batched schema changes in Convex, providing the persistent state needed to record progress, handle failures, and ensure idempotent execution across processing batches.