convex-migration-helper

Name: convex-migration-helper
Availability: InStock
Author: vanities

Plan Convex schema and data migrations using a widen-migrate-narrow strategy.

5|Updated Apr 29, 2020

Search Tags:#typescript #database migrations #data integrity #schema change #convex #backfill #zero downtime

Ready to run

npx skills add https://github.com/vanities/bitchan --skill convex-migration-helper-vanities

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: convex-migration-helper
Source: https://github.com/vanities/bitchan/tree/main/web/.agents/skills/convex-migration-helper
Command: npx skills add https://github.com/vanities/bitchan --skill convex-migration-helper-vanities

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It prevents breaking Convex deployments by guiding you through schema and data migrations that respect Convex’s “data at rest must match schema” validation rules.

Core Features & Use Cases

Widen → migrate → narrow workflow: Enables zero-downtime schema changes by first making fields compatible, then backfilling existing documents, and only then tightening the schema.
Online migration safety: Ensures your migration strategy accounts for documents created during the migration window by supporting dual-read/dual-write patterns.
Operational guardrails: Helps you choose when to use the migrations component, avoid common pitfalls (like making required fields before backfilling), and verify completion via status checks or queries.
What you can fix: Adding required fields safely, changing field types, splitting/merging table structures, renaming/deprecating fields, and migrating nested-to-relational data.

Quick Start

Ask the AI to plan your specific breaking schema change for Convex and produce a widen–migrate–narrow deployment plan plus the migration component steps needed to backfill existing data.

Frequently Asked Questions about convex-migration-helper

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

FAQPage Schema

How do I handle Convex schema migrations without downtime when changing field types?▼

Convex schema migrations use a widen-migrate-narrow strategy to achieve zero downtime. You first make schema fields compatible, backfill existing documents via batched resumable migrations, then tighten the schema validation.

Why does adding a required field break my Convex deployment?▼

Adding a required field breaks Convex deployments because existing data at rest fails schema validation. You must widen the schema first, backfill all existing documents with the new field, then narrow the schema to enforce the required constraint.

What is the best way to rename or delete a field in a Convex production database?▼

The best way to rename or delete a Convex field is using an online migration pattern with dual-read and dual-write handling. This accounts for documents created during the migration window, ensuring data integrity before removing the old field.

Can I use the migrations component for batched backfills on Convex?▼

Yes, you can use the @convex-dev/migrations component for batched and resumable backfills. It provides operational guardrails to verify completion via status checks when applying schema changes in production or dev environments.

How do I migrate nested data to a relational table structure in Convex?▼

Migrating nested data to relational tables in Convex requires splitting table structures using a planned widen-migrate-narrow workflow. You extract nested data into a new table, backfill relational references, and update application logic before narrowing.

When should I avoid making schema fields required in Convex?▼

You should avoid making schema fields required in Convex until after all existing documents are backfilled. Tightening the schema prematurely will cause validation errors for data at rest that lacks the new required field.