convex-migration-helper

Execute Convex schema and data migrations using a widen–migrate–narrow workflow.

Updated Jun 8, 2024

Search Tags:#database migrations #schema evolution #convex #zero downtime #data backfill #migration safety #widen migrate narrow

Ready to run

npx skills add https://github.com/shadeiskndr/portfolio --skill convex-migration-helper-shadeiskndr

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you plan and execute safe Convex schema and data migrations so you can ship breaking changes without breaking deployments or losing data.

Core Features & Use Cases

widen–migrate–narrow workflow: guides you through multi-deploy migration sequencing that matches Convex’s schema validation constraints.
online migration safety: explains how to handle reads/writes during the migration window when both old and new data shapes exist.
production-grade patterns: covers common breakages like required-field additions, type/shape changes, splitting/merging tables, and renames/deletions via deprecation.

Quick Start

Ask the Skill to outline a widen–migrate–narrow plan for your specific Convex breaking schema change and to map each deploy step to the required migration logic.

Frequently Asked Questions about convex-migration-helper

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

FAQPage Schema

How do I execute Convex schema migrations with zero downtime?▼

Execute Convex schema migrations with zero downtime by applying a widen–migrate–narrow deployment workflow. This multi-deploy sequence ensures service availability while handling both old and new document formats throughout the migration window.

What is the widen–migrate–narrow workflow for database migrations?▼

The widen–migrate–narrow workflow is a multi-deploy migration sequencing strategy that matches Convex schema validation constraints. It guides you through expanding schema rules, backfilling data, and then restricting rules to safely ship breaking changes.

How do I handle data backfills when changing field types or splitting tables in Convex?▼

Handle data backfills during Convex table splits, merges, or type changes by using online migration safety patterns. This ensures reads and writes remain functional while both old and new data shapes coexist during the production rollout.

Can I rename or delete required fields in Convex without breaking production deployments?▼

You can rename or delete required fields in Convex without breaking deployments by using deprecation patterns. The migration Skill plans the required field additions and shape restructuring across multiple deploys to maintain service availability.

When do I need to use online migrations for Convex schema evolution?▼

You need online migrations for Convex schema evolution when shipping breaking changes like required field additions, type restructuring, or table merges. This process handles concurrent reads and writes when both old and new document formats exist.

What are the limitations of migrating Convex data without a multi-deploy workflow?▼

Migrating Convex data without a multi-deploy workflow risks breaking deployments and losing data because Convex schema validation constraints reject mismatched document shapes. Single-deploy updates fail when old and new data formats collide.