# Migrate

> Migrate the schema + backfill data on a deployed Convex app (optional-first, then backfill, then require). TRIGGER on a live-schema-change/backfill request.

- Skill: `get-convex/migrate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add get-convex/migrate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/get-convex/migrate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: get-convex (https://skillmd.com/u/get-convex)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/get-convex/migrate

---


# 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.

## Steps
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.