Skip to main content
affpapa.org
RU EN
skill CX Codex

convex-migrate — Claude Code skill: Convex schema migrations

A skill that walks the agent through schema changes and data backfills on a deployed Convex app using @convex-dev/migrations. Useful when the app is already live.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add convex/agent-skills --skill convex-migrate -a claude-code
Open on GitHub

What convex-migrate does

The skill lays out the order of work for changing a schema on a running Convex 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 brings old rows into the new shape. Once the backfill finishes, the validator can be tightened and the field made required.

Inside there is a single SKILL.md with the workflow and its rules. The rules are blunt: never tighten a validator before the backfill completes, add fields as optional first, check row counts before and after. That first rule is the one that matters — do it the other way and existing rows stop passing validation, which breaks the live app.

The skill does not run the migration itself. It gives the agent a sequence to follow; the migration code and the run stay with you.

What it helps with

  • change a schema on a deployed app without breaking live queries
  • add a field and fill it in on existing rows
  • write a backfill with @convex-dev/migrations
  • compare row counts before and after a migration
  • make a field required only once the data is in shape

Example prompts for the agent

  • help me migrate the Convex schema: add the field as optional, write the backfill, check the rows
  • I need to tighten the validator after the backfill — walk me through the steps
  • write a @convex-dev/migrations migration for the existing rows

How to install convex-migrate

1Skills CLI (Vercel)

npx skills add convex/agent-skills --skill convex-migrate -a claude-code

2Manually: put the files in place

~/.claude/skills/convex-migrate/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/convex-migrate/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about convex-migrate

How do I install convex-migrate in Claude?

Run npx skills add convex/agent-skills --skill convex-migrate -a claude-code. The skill lands in ~/.claude/skills/convex-migrate/SKILL.md.

What does convex-migrate do?

It guides the agent through a schema migration and data backfill on a deployed Convex app with @convex-dev/migrations.

Why can't I make the field required right away?

The validator rejects existing rows, which breaks the live app. Backfill first, tighten later.

Source text

SKILL.md · Apache-2.0 
---
name: convex-migrate
description: "Migrate schema + backfill data on a deployed Convex app using @convex-dev/migrations."
---

<!-- GENERATED from convex-agents content/capabilities/migrate.json — do not edit by hand. -->

# Migrate the schema / data on a live app

Change a deployed schema without breaking existing data: stage the schema change, install @convex-dev/migrations, write a backfill that makes old rows valid, run it, and verify before tightening the validator.

## Workflow

1. Make the new field optional first (so deploy doesn't reject existing rows).
2. Install @convex-dev/migrations; write a migration that backfills/transforms existing rows.
3. Run the migration; verify all rows are valid.
4. Tighten the validator (make the field required) once the backfill is complete.

## Rules

- Never tighten a validator before the backfill completes — it rejects existing rows and breaks the live app.
- Add new fields as optional first, migrate, then require.
- Verify row counts before and after.

© convex · Apache-2.0 · convex/agent-skills

Similar skills

All skills for Data and databases →
convex-migrations waynesutton Walks a live Convex schema change through six steps: optional field, batched backfill, validator flip, cleanup. Useful when npx convex dev rejects existing documents. CX Codex +1 2,600installs convex-schema-validator waynesutton Designs Convex tables, validators, indexes, and document relationships in convex/schema.ts. Use it when a schema changes or validation fails during development. CX Codex +1 3,000installs convex Mindrally Tells the agent how to write Convex code: queries, mutations, actions, indexes and file uploads. Useful once Convex is your backend. CX Codex +1 651installs migration JuliusBrussee Enforces reversible, compatibility-safe transitions for schema, data, and API updates. Useful whenever data loss or rollout downtime is unacceptable. CX Codex +1 103,900installs planetscale-schema-recommendations-agent-loop planetscale Turns open PlanetScale schema recommendations into a plan, issue, branch or PR. It never applies production changes on its own. CX Codex +1 1,800installs specsfy-aux-database promovaweb Maintains .specsfy/DATABASE.md with tables of databases, schemas, fields, relations and migrations so the data map matches the code. CX Codex +1 437installs

From the same set32

convex-quickstart Turns a one-sentence idea into a running barebones Next.js + Convex app, with an anonymous dev backend and no publish step. CX Codex +1 131,100installs convex-create-component A skill to design and build reusable Convex components with isolated tables and a clear API boundary. Useful when you need to extract backend logic into a self-contained module or package an integration that owns its own data. CX Codex +1 130,900installs convex Router skill for Convex backend work: it picks the right convex-* procedure for your task and pulls current instructions from a served capability catalog. CX Codex +1 108,000installs convex-expert A skill for any code under convex/: functions, schemas, indexes, validators. Useful when your agent writes Convex backend code. CX Codex +1 36,200installs convex-authz Audits and hardens Convex backend authorization against four defect patterns. Fixes impersonation through arguments, missing ownership checks, and unauthorized writes. CX Codex +1 36,100installs convex-auth This skill adds passkey, OAuth, or password sign-in to a Convex app. Use it when auth needs to reach the server config, client hooks, and route guards. CX Codex +1 36,200installs convex-optimize The skill audits an existing Convex app and turns the findings into a plan: security, scale, component upgrades, observability. CX Codex +1 36,000installs convex-deploy-guard Classifies and announces the target Convex deployment before running mutations. Requires explicit approval for production and enforces read-only session modes. CX Codex +1 36,000installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor