Hi @thin bane. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
#Do migrations run serially?
peak aspenBOT
Yes, migrations in Convex run serially. The startMigrationsSerially function will run each migration that hasn't finished, one at a time. If a migration had already completed, it will skip it. If a migration had partial progress, it will resume from where it left off. If a migration is already in progress when attempted, it will no-op.
If a migration fails or is canceled, it will not continue to the next migration, in case you had some dependencies between the migrations. You would need to call the series again to retry. Here's an example of how to use startMigrationsSerially:
import { startMigrationsSerially } from "convex-helpers/server/migrations";
import { internalMutation } from "./_generated/server";
export default internalMutation(async (ctx) => {
await startMigrationsSerially(ctx, [
internal.migrations.myMigration,
internal.migrations.myOtherMutation,
//...
]);
});
If you start multiple serial migrations, they can run in parallel if they don't overlap on functions. If they have a function in common and one completes before the other attempts it, the second will just skip it. If they have a function in common and one is in progress, the second will no-op and not run any further migrations in its series.
Regarding error handling, if an error is thrown during a mutation, everything will be rolled back in that mutation, not just a specific section of code. This is because Convex doesn't actually apply the changes to the database until the end of the mutation. If an error propagates all the way up, the changes are not applied to the database.
For more details, you can refer to these sources:
- Running a series of default migrations from code (https://stack.convex.dev/migrating-data-with-mutations#running-a-series-of-default-migrations-from-code)
- Discord support thread: Clerk + Convex: Can't use fetch() in queries and mutations. Please consider using an action (https://discord.com/channels/1019350475847499849/1241155478780776678)