1# Migration Patterns Reference
2 
3Common migration patterns, zero-downtime strategies, and verification techniques
4for Convex schema and data migrations.
5 
6## Adding a Required Field
7 
8```typescript
9// Deploy 1: Schema allows both states
10users: defineTable({
11  name: v.string(),
12  role: v.optional(v.union(v.literal("user"), v.literal("admin"))),
13});
14 
15// Migration: backfill the field
16export const addDefaultRole = migrations.define({
17  table: "users",
18  migrateOne: async (ctx, user) => {
19    if (user.role === undefined) {
20      await ctx.db.patch(user._id, { role: "user" });
21    }
22  },
23});
24 
25// Deploy 2: After migration completes, make it required
26users: defineTable({
27  name: v.string(),
28  role: v.union(v.literal("user"), v.literal("admin")),
29});
30```
31 
32## Deleting a Field
33 
34Mark the field optional first, migrate data to remove it, then remove from
35schema:
36 
37```typescript
38// Deploy 1: Make optional
39// isPro: v.boolean()  -->  isPro: v.optional(v.boolean())
40 
41// Migration
42export const removeIsPro = migrations.define({
43  table: "teams",
44  migrateOne: async (ctx, team) => {
45    if (team.isPro !== undefined) {
46      await ctx.db.patch(team._id, { isPro: undefined });
47    }
48  },
49});
50 
51// Deploy 2: Remove isPro from schema entirely
52```
53 
54## Changing a Field Type
55 
56Prefer creating a new field. You can combine adding and deleting in one
57migration:
58 
59```typescript
60// Deploy 1: Add new field, keep old field optional
61// isPro: v.boolean()  -->  isPro: v.optional(v.boolean()), plan: v.optional(...)
62 
63// Migration: convert old field to new field
64export const convertToEnum = migrations.define({
65  table: "teams",
66  migrateOne: async (ctx, team) => {
67    if (team.plan === undefined) {
68      await ctx.db.patch(team._id, {
69        plan: team.isPro ? "pro" : "basic",
70        isPro: undefined,
71      });
72    }
73  },
74});
75 
76// Deploy 2: Remove isPro from schema, make plan required
77```
78 
79## Splitting Nested Data Into a Separate Table
80 
81```typescript
82export const extractPreferences = migrations.define({
83  table: "users",
84  migrateOne: async (ctx, user) => {
85    if (user.preferences === undefined) return;
86 
87    const existing = await ctx.db
88      .query("userPreferences")
89      .withIndex("by_user", (q) => q.eq("userId", user._id))
90      .first();
91 
92    if (!existing) {
93      await ctx.db.insert("userPreferences", {
94        userId: user._id,
95        ...user.preferences,
96      });
97    }
98 
99    await ctx.db.patch(user._id, { preferences: undefined });
100  },
101});
102```
103 
104Make sure your code is already writing to the new `userPreferences` table for
105new users before running this migration, so you don't miss documents created
106during the migration window.
107 
108## Cleaning Up Orphaned Documents
109 
110```typescript
111export const deleteOrphanedEmbeddings = migrations.define({
112  table: "embeddings",
113  migrateOne: async (ctx, doc) => {
114    const chunk = await ctx.db
115      .query("chunks")
116      .withIndex("by_embedding", (q) => q.eq("embeddingId", doc._id))
117      .first();
118 
119    if (!chunk) {
120      await ctx.db.delete(doc._id);
121    }
122  },
123});
124```
125 
126## Zero-Downtime Strategies
127 
128During the migration window, your app must handle both old and new data formats.
129There are two main strategies.
130 
131### Dual Write (Preferred)
132 
133Write to both old and new structures. Read from the old structure until
134migration is complete.
135 
1361. Deploy code that writes both formats, reads old format
1372. Run migration on existing data
1383. Deploy code that reads new format, still writes both
1394. Deploy code that only reads and writes new format
140 
141This is preferred because you can safely roll back at any point, the old format
142is always up to date.
143 
144```typescript
145// Bad: only writing to new structure before migration is done
146export const createTeam = mutation({
147  args: { name: v.string(), isPro: v.boolean() },
148  handler: async (ctx, args) => {
149    await ctx.db.insert("teams", {
150      name: args.name,
151      plan: args.isPro ? "pro" : "basic",
152    });
153  },
154});
155 
156// Good: writing to both structures during migration
157export const createTeam = mutation({
158  args: { name: v.string(), isPro: v.boolean() },
159  handler: async (ctx, args) => {
160    const plan = args.isPro ? "pro" : "basic";
161    await ctx.db.insert("teams", {
162      name: args.name,
163      isPro: args.isPro,
164      plan,
165    });
166  },
167});
168```
169 
170### Dual Read
171 
172Read both formats. Write only the new format.
173 
1741. Deploy code that reads both formats (preferring new), writes only new format
1752. Run migration on existing data
1763. Deploy code that reads and writes only new format
177 
178This avoids duplicating writes, which is useful when having two copies of data
179could cause inconsistencies. The downside is that rolling back to before step 1
180is harder, since new documents only have the new format.
181 
182```typescript
183// Good: reading both formats, preferring new
184function getTeamPlan(team: Doc<"teams">): "basic" | "pro" {
185  if (team.plan !== undefined) return team.plan;
186  return team.isPro ? "pro" : "basic";
187}
188```
189 
190## Small Table Shortcut
191 
192For small tables (a few thousand documents at most), you can migrate in a single
193`internalMutation` without the component:
194 
195```typescript
196import { internalMutation } from "./_generated/server";
197 
198export const backfillSmallTable = internalMutation({
199  handler: async (ctx) => {
200    const docs = await ctx.db.query("smallConfig").collect();
201    for (const doc of docs) {
202      if (doc.newField === undefined) {
203        await ctx.db.patch(doc._id, { newField: "default" });
204      }
205    }
206  },
207});
208```
209 
210```bash
211npx convex run migrations:backfillSmallTable
212```
213 
214Only use `.collect()` when you are certain the table is small. For anything
215larger, use the migrations component.
216 
217## Verifying a Migration
218 
219Query to check remaining unmigrated documents:
220 
221```typescript
222import { query } from "./_generated/server";
223 
224export const verifyMigration = query({
225  handler: async (ctx) => {
226    const remaining = await ctx.db
227      .query("users")
228      .filter((q) => q.eq(q.field("role"), undefined))
229      .take(10);
230 
231    return {
232      complete: remaining.length === 0,
233      sampleRemaining: remaining.map((u) => u._id),
234    };
235  },
236});
237```
238 
239Or use the component's built-in status monitoring:
240 
241```bash
242npx convex run --component migrations lib:getStatus --watch
243```
244