# Convex Migration

> guidance on how to properly do data migrations in Convex

- Skill: `majiayu000/convex-migration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/convex-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/convex-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/convex-migration

---


**[Full docs](https://www.convex.dev/components/migrations)**

Use `@convex-dev/migrations` in `convex/migrations.ts` (reference `convex_migrations.md` for full guidance). The standard flow is:

- loosen schema/app to tolerate old+new values
- add `migrations.define({ table, migrateOne })` in `convex/migrations.ts` (idempotent; skip no‑ops; no external APIs).
- dry run: `npx convex run migrations:runYourFn '{"dryRun":true,"cursor":null}'`
- full run: `npx convex run migrations:runYourFn '{"cursor":null}'`*
- monitor: `npx convex run --component migrations lib:getStatus --watch`
- cancel: `npx convex run --component migrations lib:cancel '{"name":"migrations:yourFnName"}'`.

*`"cursor":null` makes it to real work from the start (as opposed to the dry-run default); omit only when resuming from a specific cursor.