convex-migrate

Migrate Convex schemas and backfill data on deployed apps using @convex-dev/migrations.

1|Updated Oct 10, 2025

Search Tags:#database #schema #migration #deploy #validator #convex #backfill

Ready to run

npx skills add https://github.com/Rocktown-Labs/rivercitymd --skill convex-migrate-rocktown-labs

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: convex-migrate
Source: https://github.com/Rocktown-Labs/rivercitymd/tree/main/.agents/skills/convex-migrate
Command: npx skills add https://github.com/Rocktown-Labs/rivercitymd --skill convex-migrate-rocktown-labs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @convex-dev/migrations.

What problem does it solve? Changing a schema on a live Convex app risks breaking existing data: tightening a validator before old rows are updated causes deploys to reject them. This Skill provides a safe, staged workflow for evolving schemas without downtime or data loss. ## Core Features & Use Cases - Staged Schema Changes: Add new fields as optional first so deploys never reject existing rows. - Data Backfills: Install @convex-dev/migrations and write migrations that transform or backfill existing rows. - Safe Validator Tightening: Verify row counts and validity before making fields required. - Use Case: You need to add a required `subscriptionTier` field to the `users` table on a production app. Deploy it as optional, run a backfill migration to populate existing users, verify all rows are valid, then tighten the validator. ## Quick Start Use the convex-migrate skill to add a required field to my Convex users table and backfill existing rows safely.

Frequently Asked Questions about convex-migrate

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

FAQPage Schema

How do I migrate a Convex schema on a live app?▼

Add the new field as optional first so the deploy does not reject existing rows, then install @convex-dev/migrations and write a migration that backfills existing rows. After verifying all rows are valid, tighten the validator to make the field required.

How do I backfill existing rows in Convex?▼

Use the @convex-dev/migrations package to write a migration that transforms or populates existing rows. Run the migration against the deployed app, then verify row counts before and after to confirm completeness.

Why does my Convex deploy reject existing rows after a schema change?▼

The validator was tightened before existing rows were backfilled, so old rows fail the new validation. Make new fields optional first, run the backfill migration, and only require the field once all rows are valid.

When should I make a new Convex field required?▼

Only after the backfill migration has completed and every existing row passes the new validator. Requiring a field before backfilling breaks the live app by rejecting existing data.

How do I verify a Convex data migration succeeded?▼

Verify row counts before and after running the migration and confirm all rows satisfy the new validator. Only proceed to tighten the schema once verification passes.