# convex-migrate

Changes a live Convex schema safely by making fields optional, backfilling old rows with @convex-dev/migrations, then requiring them.

Skill by Convex. Category: Data and backend.

## Install

Project (for this project only):

```sh
npx skills add get-convex/agent-skills --skill convex-migrate
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add get-convex/agent-skills --skill convex-migrate -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 30679. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/get-convex/agent-skills/convex-migrate)

## Source

[Open the source](https://github.com/get-convex/agent-skills/tree/HEAD/skills/convex-migrate). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
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.
````

- Previous: [convex-authz](https://syn4pse.dev/terminal/convex-authz.md)
- Next: [convex-docs](https://syn4pse.dev/terminal/convex-docs.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
