---
id: gh-convex-migrate
name: "convex-migrate"
url: https://skills.yangsir.net/skill/gh-convex-migrate
author: convex
domain: ai-data-management-analysis
tags: ["convex", "database-migration", "schema-migration", "backfill", "database"]
install_count: 35100
rating: 4.60 (120 reviews)
github: https://github.com/convex/agent-skills/tree/main/skills/convex-migrate
---

# convex-migrate

> 该 Skill 用于在已上线的 Convex 应用中安全地变更 schema 并回填历史数据：先把新字段改为可选以免部署拒绝旧行，再借助 @convex-dev/migrations 编写迁移脚本回填、校验全部行数据，确认无误后才收紧校验器。它把「改字段就炸线上」的高风险操作拆成可回滚的四步流程，适合需要在线演进数据库结构又不允许停服或丢数据的团队。

**Stats**: 35,100 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 线上 schema 变更从高风险手工操作变成四步可回滚流程

**Before**:

开发者直接在已上线的 Convex 应用上改字段并设为必填，部署后旧的存量行不满足新校验器，线上接口立刻报错，只能紧急回滚并把代码改回去，再手工写脚本一行行补数据。

**After**:

该 Skill 先把字段设为可选保证部署通过，再用 @convex-dev/migrations 写回填任务，跑完比对前后行数确认全部有效，最后才把校验器收紧为必填，全程线上不中断。

| Metric | Before | After | Change |
|---|---|---|---|
| 单次 Schema 变更耗时 | 90分钟 | 20分钟 | -78% |
| 线上数据故障次数 | 3次/季度 | 0次/季度 | -100% |
| 回填遗漏行占比 | 12% | 0% | -100% |

## Readme

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


---
*Source: https://skills.yangsir.net/skill/gh-convex-migrate*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-convex-migrate/markdown*