1# Migrations Component Reference
2 
3Complete guide to the
4[`@convex-dev/migrations`](https://www.convex.dev/components/migrations)
5component for batched, resumable Convex data migrations.
6 
7## Installation
8 
9```bash
10npm install @convex-dev/migrations
11```
12 
13## Setup
14 
15```typescript
16// convex/convex.config.ts
17import { defineApp } from "convex/server";
18import migrations from "@convex-dev/migrations/convex.config.js";
19 
20const app = defineApp();
21app.use(migrations);
22export default app;
23```
24 
25```typescript
26// convex/migrations.ts
27import { Migrations } from "@convex-dev/migrations";
28import { components } from "./_generated/api.js";
29import { DataModel } from "./_generated/dataModel.js";
30 
31export const migrations = new Migrations<DataModel>(components.migrations);
32export const run = migrations.runner();
33```
34 
35The `DataModel` type parameter is optional but provides type safety for
36migration definitions.
37 
38## Define a Migration
39 
40The `migrateOne` function processes a single document. The component handles
41batching and pagination automatically.
42 
43```typescript
44// convex/migrations.ts
45export const addDefaultRole = migrations.define({
46  table: "users",
47  migrateOne: async (ctx, user) => {
48    if (user.role === undefined) {
49      await ctx.db.patch(user._id, { role: "user" });
50    }
51  },
52});
53```
54 
55Shorthand: if you return an object, it is applied as a patch automatically.
56 
57```typescript
58export const clearDeprecatedField = migrations.define({
59  table: "users",
60  migrateOne: () => ({ legacyField: undefined }),
61});
62```
63 
64## Run a Migration
65 
66From the CLI:
67 
68```bash
69# Define a one-off runner in convex/migrations.ts:
70#   export const runIt = migrations.runner(internal.migrations.addDefaultRole);
71npx convex run migrations:runIt
72 
73# Or use the general-purpose runner
74npx convex run migrations:run '{"fn": "migrations:addDefaultRole"}'
75```
76 
77Programmatically from another Convex function:
78 
79```typescript
80await migrations.runOne(ctx, internal.migrations.addDefaultRole);
81```
82 
83## Run Multiple Migrations in Order
84 
85```typescript
86export const runAll = migrations.runner([
87  internal.migrations.addDefaultRole,
88  internal.migrations.clearDeprecatedField,
89  internal.migrations.normalizeEmails,
90]);
91```
92 
93```bash
94npx convex run migrations:runAll
95```
96 
97If one fails, it stops and will not continue to the next. Call it again to retry
98from where it left off. Completed migrations are skipped automatically.
99 
100## Dry Run
101 
102Test a migration before committing changes:
103 
104```bash
105npx convex run migrations:runIt '{"dryRun": true}'
106```
107 
108This runs one batch and then rolls back, so you can see what it would do without
109changing any data.
110 
111## Check Migration Status
112 
113```bash
114npx convex run --component migrations lib:getStatus --watch
115```
116 
117## Cancel a Running Migration
118 
119```bash
120npx convex run --component migrations lib:cancel '{"name": "migrations:addDefaultRole"}'
121```
122 
123Or programmatically:
124 
125```typescript
126await migrations.cancel(ctx, internal.migrations.addDefaultRole);
127```
128 
129## Run Migrations on Deploy
130 
131Chain migration execution after deploying:
132 
133```bash
134npx convex deploy --cmd 'npm run build' && npx convex run migrations:runAll --prod
135```
136 
137## Configuration Options
138 
139### Custom Batch Size
140 
141If documents are large or the table has heavy write traffic, reduce the batch
142size to avoid transaction limits or OCC conflicts:
143 
144```typescript
145export const migrateHeavyTable = migrations.define({
146  table: "largeDocuments",
147  batchSize: 10,
148  migrateOne: async (ctx, doc) => {
149    // migration logic
150  },
151});
152```
153 
154### Migrate a Subset Using an Index
155 
156Process only matching documents instead of the full table:
157 
158```typescript
159export const fixEmptyNames = migrations.define({
160  table: "users",
161  customRange: (query) => query.withIndex("by_name", (q) => q.eq("name", "")),
162  migrateOne: () => ({ name: "<unknown>" }),
163});
164```
165 
166### Parallelize Within a Batch
167 
168By default each document in a batch is processed serially. Enable parallel
169processing if your migration logic does not depend on ordering:
170 
171```typescript
172export const clearField = migrations.define({
173  table: "myTable",
174  parallelize: true,
175  migrateOne: () => ({ optionalField: undefined }),
176});
177```
178