1---
2name: convex-migration-helper
3description:
4  Plans Convex schema and data migrations with widen-migrate-narrow and
5  @convex-dev/migrations. Use for breaking schema changes, backfills, table
6  reshaping, or zero-downtime rollouts.
7---
8 
9# Convex Migration Helper
10 
11Safely migrate Convex schemas and data when making breaking changes.
12 
13## When to Use
14 
15- Adding new required fields to existing tables
16- Changing field types or structure
17- Splitting or merging tables
18- Renaming or deleting fields
19- Migrating from nested to relational data
20 
21## When Not to Use
22 
23- Greenfield schema with no existing data in production or dev
24- Adding optional fields that do not need backfilling
25- Adding new tables with no existing data to migrate
26- Adding or removing indexes with no correctness concern
27- Questions about Convex schema design without a migration need
28 
29## Key Concepts
30 
31### Schema Validation Drives the Workflow
32 
33Convex will not let you deploy a schema that does not match the data at rest.
34This is the fundamental constraint that shapes every migration:
35 
36- You cannot add a required field if existing documents don't have it
37- You cannot change a field's type if existing documents have the old type
38- You cannot remove a field from the schema if existing documents still have it
39 
40This means migrations follow a predictable pattern: **widen the schema, migrate
41the data, narrow the schema**.
42 
43### Online Migrations
44 
45Convex migrations run online, meaning the app continues serving requests while
46data is updated asynchronously in batches. During the migration window, your
47code must handle both old and new data formats.
48 
49### Prefer New Fields Over Changing Types
50 
51When changing the shape of data, create a new field rather than modifying an
52existing one. This makes the transition safer and easier to roll back.
53 
54### Don't Delete Data
55 
56Unless you are certain, prefer deprecating fields over deleting them. Mark the
57field as `v.optional` and add a code comment explaining it is deprecated and why
58it existed.
59 
60## Safe Changes (No Migration Needed)
61 
62### Adding Optional Field
63 
64```typescript
65// Before
66users: defineTable({
67  name: v.string(),
68});
69 
70// After - safe, new field is optional
71users: defineTable({
72  name: v.string(),
73  bio: v.optional(v.string()),
74});
75```
76 
77### Adding New Table
78 
79```typescript
80posts: defineTable({
81  userId: v.id("users"),
82  title: v.string(),
83}).index("by_user", ["userId"]);
84```
85 
86### Adding Index
87 
88```typescript
89users: defineTable({
90  name: v.string(),
91  email: v.string(),
92}).index("by_email", ["email"]);
93```
94 
95## Breaking Changes: The Deployment Workflow
96 
97Every breaking migration follows the same multi-deploy pattern:
98 
99**Deploy 1 - Widen the schema:**
100 
1011. Update schema to allow both old and new formats (e.g., add optional new
102   field)
1032. Update code to handle both formats when reading
1043. Update code to write the new format for new documents
1054. Deploy
106 
107**Between deploys - Migrate data:**
108 
1095. Run migration to backfill existing documents
1106. Verify all documents are migrated
111 
112**Deploy 2 - Narrow the schema:**
113 
1147. Update schema to require the new format only
1158. Remove code that handles the old format
1169. Deploy
117 
118## Using the Migrations Component
119 
120For any non-trivial migration, use the
121[`@convex-dev/migrations`](https://www.convex.dev/components/migrations)
122component. It handles batching, cursor-based pagination, state tracking, resume
123from failure, dry runs, and progress monitoring.
124 
125See `references/migrations-component.md` for installation, setup, defining and
126running migrations, dry runs, status monitoring, and configuration options.
127 
128## Common Migration Patterns
129 
130See `references/migration-patterns.md` for complete patterns with code examples
131covering:
132 
133- Adding a required field
134- Deleting a field
135- Changing a field type
136- Splitting nested data into a separate table
137- Cleaning up orphaned documents
138- Zero-downtime strategies (dual write, dual read)
139- Small table shortcut (single internalMutation without the component)
140- Verifying a migration is complete
141 
142## Common Pitfalls
143 
1441. **Making a field required before migrating data**: Convex rejects the deploy
145   because existing documents lack the field. Always widen the schema first.
1462. **Using `.collect()` on large tables**: Hits transaction limits or causes
147   timeouts. Use the migrations component for proper batched pagination.
148   `.collect()` is only safe for tables you know are small.
1493. **Not writing the new format before migrating**: Documents created during the
150   migration window will be missed, leaving unmigrated data after the migration
151   "completes."
1524. **Skipping the dry run**: Use `dryRun: true` to validate migration logic
153   before committing changes to production data. Catches bugs before they touch
154   real documents.
1555. **Deleting fields prematurely**: Prefer deprecating with `v.optional` and a
156   comment. Only delete after you are confident the data is no longer needed and
157   no code references it.
1586. **Using crons for migration batches**: The migrations component handles
159   batching via recursive scheduling internally. Crons require manual cleanup
160   and an extra deploy to remove.
161 
162## Migration Checklist
163 
164- [ ] Identify the breaking change and plan the multi-deploy workflow
165- [ ] Update schema to allow both old and new formats
166- [ ] Update code to handle both formats when reading
167- [ ] Update code to write the new format for new documents
168- [ ] Deploy widened schema and updated code
169- [ ] Define migration using the `@convex-dev/migrations` component
170- [ ] Test with `dryRun: true`
171- [ ] Run migration and monitor status
172- [ ] Verify all documents are migrated
173- [ ] Update schema to require new format only
174- [ ] Clean up code that handled old format
175- [ ] Deploy final schema and code
176- [ ] Remove migration code once confirmed stable
177