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);
32```
33 
34The `DataModel` type parameter is optional but provides type safety for
35migration definitions.
36 
37## Define a Migration
38 
39The `migrateOne` function processes a single document. The component handles
40batching and pagination automatically.
41 
42```typescript
43// convex/migrations.ts
44export const addDefaultRole = migrations.define({
45  table: "users",
46  migrateOne: async (ctx, user) => {
47    if (user.role === undefined) {
48      await ctx.db.patch(user._id, { role: "user" });
49    }
50  },
51});
52```
53 
54Shorthand: if you return an object, it is applied as a patch automatically.
55 
56```typescript
57export const clearDeprecatedField = migrations.define({
58  table: "users",
59  migrateOne: () => ({ legacyField: undefined }),
60});
61```
62 
63## Run a Migration
64 
65From the CLI:
66 
67```bash
68npx convex run migrations:addDefaultRole
69 
70# Pass --prod to run in production.
71npx convex run migrations:addDefaultRole --prod
72```
73 
74The migration exported by `migrations.define` is directly callable from the CLI
75or dashboard. You do not need a separate one-off runner for normal single
76migrations.
77 
78If you want a general-purpose runner that accepts a migration name, define one:
79 
80```typescript
81export const run = migrations.runner();
82```
83 
84Then call it with the full function name:
85 
86```bash
87npx convex run migrations:run '{"fn": "migrations:addDefaultRole"}'
88```
89 
90Programmatically from another Convex function:
91 
92```typescript
93await migrations.runOne(ctx, internal.migrations.addDefaultRole);
94```
95 
96## Run Multiple Migrations in Order
97 
98For a short ad hoc series, pass `next` when starting the first migration:
99 
100```bash
101npx convex run migrations:addDefaultRole '{"next":["migrations:clearDeprecatedField","migrations:normalizeEmails"]}'
102```
103 
104For a reusable series, define a runner:
105 
106```typescript
107export const runAll = migrations.runner([
108  internal.migrations.addDefaultRole,
109  internal.migrations.clearDeprecatedField,
110  internal.migrations.normalizeEmails,
111]);
112```
113 
114```bash
115npx convex run migrations:runAll
116```
117 
118If one fails, it stops and will not continue to the next. Call it again to retry
119from where it left off. Completed migrations are skipped automatically.
120 
121Programmatically from another Convex function:
122 
123```typescript
124await migrations.runSerially(ctx, [
125  internal.migrations.addDefaultRole,
126  internal.migrations.clearDeprecatedField,
127  internal.migrations.normalizeEmails,
128]);
129```
130 
131## Dry Run
132 
133Test a migration before committing changes:
134 
135```bash
136npx convex run migrations:addDefaultRole '{"dryRun": true}'
137```
138 
139This runs one batch and then rolls back, so you can see what it would do without
140changing any data.
141 
142## Restart a Migration
143 
144Pass `reset: true` to restart a migration from the beginning:
145 
146```bash
147npx convex run migrations:addDefaultRole '{"reset": true}'
148```
149 
150If you specify `next` or run a defined series, `reset: true` resets the cursor
151for all migrations in the group.
152 
153## Check Migration Status
154 
155```bash
156npx convex run --component migrations lib:getStatus --watch
157```
158 
159## Cancel a Running Migration
160 
161```bash
162npx convex run --component migrations lib:cancel '{"name": "migrations:addDefaultRole"}'
163```
164 
165Or programmatically:
166 
167```typescript
168await migrations.cancel(ctx, internal.migrations.addDefaultRole);
169```
170 
171## Run Migrations on Deploy
172 
173Chain migration execution after deploying:
174 
175```bash
176npx convex deploy --cmd 'npm run build' && npx convex run migrations:runAll --prod
177```
178 
179## Configuration Options
180 
181### Custom Batch Size
182 
183If documents are large or the table has heavy write traffic, reduce the batch
184size to avoid transaction limits or OCC conflicts:
185 
186```typescript
187export const migrateHeavyTable = migrations.define({
188  table: "largeDocuments",
189  batchSize: 10,
190  migrateOne: async (ctx, doc) => {
191    // migration logic
192  },
193});
194```
195 
196### Migrate a Subset Using an Index
197 
198Process only matching documents instead of the full table:
199 
200```typescript
201export const fixEmptyNames = migrations.define({
202  table: "users",
203  customRange: (query) => query.withIndex("by_name", (q) => q.eq("name", "")),
204  migrateOne: () => ({ name: "<unknown>" }),
205});
206```
207 
208### Parallelize Within a Batch
209 
210By default each document in a batch is processed serially. Enable parallel
211processing if your migration logic does not depend on ordering:
212 
213```typescript
214export const clearField = migrations.define({
215  table: "myTable",
216  parallelize: true,
217  migrateOne: () => ({ optionalField: undefined }),
218});
219```
220