convex-migrate

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

Updated May 26, 2026
One-click install
npx skills add https://github.com/Albo-Club/albo-os --skill convex-migrate-albo-club
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: convex-migrate
Source: https://github.com/Albo-Club/albo-os/tree/main/.agents/skills/convex-migrate
Command: npx skills add https://github.com/Albo-Club/albo-os --skill convex-migrate-albo-club

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @convex-dev/migrations.

What problem does it solve? Changing the schema of a live Convex app risks breaking existing data: tightening a validator before old rows are updated causes the deployment to reject them. This Skill provides a safe, staged workflow for evolving a production schema without downtime or data loss. ## Core Features & Use Cases - Staged schema changes: Add new fields as optional first so the deploy never rejects existing rows. - Guided backfills: Install @convex-dev/migrations and write a migration that transforms or backfills existing rows. - Verification before tightening: Check row counts and validity before making a field required. - Use Case: You need to add a required role field to an existing users table in production. The Skill walks you through adding it as optional, running a backfill migration, verifying all rows, and only then tightening the validator. ## Quick Start Ask the agent to migrate my live Convex schema by adding a new required field and backfilling existing rows with @convex-dev/migrations.

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 accepts existing rows, then install @convex-dev/migrations and write a migration that backfills old 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 function that transforms or fills existing documents. Run the migration against your deployment, then verify row counts before and after to confirm every row was updated.

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

The validator was tightened before existing data was migrated, so old rows fail the new schema. Always add fields as optional first, run the backfill migration, and only make the field required once all rows are valid.

When should I make a new Convex field required?

Only after the backfill migration has completed and you have verified that every existing row contains a valid value for the field. Tightening the validator earlier breaks the live app by rejecting legacy rows.