Hi @worn plume. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
#Migrations
neon pebbleBOT
When running a migration in Convex, by default, the migration starts from the beginning of the table (or the specified subset if you're using customRange).
If you're running a migration for the first time, it will start with a null cursor, which represents the beginning of the table. The migration processes documents in batches, with a default batch size that can be configured.
If a migration was previously started but didn't complete (due to an error or being stopped), when you run it again, it will automatically resume from where it left off using the saved cursor position, unless you explicitly specify a different cursor.
You can control the starting point of a migration in several ways:
- To start from the beginning, you can explicitly pass
nullfor the cursor:
npx convex run migrations:runIt '{cursor: null}'
- To resume from a specific point, you can pass a valid cursor value that you obtained from a previous run:
npx convex run migrations:runIt '{cursor: "your-cursor-value"}'
- If you want to process only a subset of documents, you can define a
customRangein your migration definition to limit which documents are processed:
export const validateRequiredField = migrations.define({
table: "myTable",
customRange: (query) =>
query.withIndex("by_requiredField", (q) => q.eq("requiredField", "")),
migrateOne: async (_ctx, doc) => {
// Migration logic here
},
});
This allows you to target specific documents based on index values rather than processing the entire table.