Migrating Ents

You can use the provided migration helpers from convex-helpers to migrate data at scale. Read the Stack article (opens in a new tab) to learn more about the helpers, then follow the steps here to use them with Ents.

Install dependencies

Make sure you have the latest version of convex-helpers installed:

npm i convex-helpers@latest

Add the migrations table to your schema

Wrap the migrationsTable definition from convex-helpers in defineEntFromTable to make it compatible with Ents:

convex/schema.ts

import { v } from "convex/values"; import {  defineEnt,  defineEntFromTable,  defineEntSchema,  getEntDefinitions, } from "convex-ents"; import { migrationsTable } from "convex-helpers/server/migrations";   const schema = defineEntSchema({  migrations: defineEntFromTable(migrationsTable),  // your other ent definitions... });   export default schema;   export const entDefinitions = getEntDefinitions(schema);

Add a migrations file

Besides the standard setup, you can create a custom mutationCtx helper to use ctx.table inside of your migrations (if you don't already have one in functions.ts):

convex/migrations.ts

import { makeMigration } from "convex-helpers/server/migrations"; import { internalMutation, MutationCtx } from "./_generated/server";   const migration = makeMigration(internalMutation, {  migrationTable: "migrations", });   async function mutationCtx(baseCtx: MutationCtx) {  return {  ...ctx,  table: entsTableFactory(ctx, entDefinitions),  db: undefined,  }; }   // In this file, or in another one if you have many migrations export const simpleMigration = migration({  table: "users",  migrateOne: async (_, user) => ({  name: user.name + " MEng.",  }), });   // Example of using `mutationCtx` to access `ctx.table` export const migrationUsingCtxTable = migration({  table: "users",  migrateOne: async (baseCtx, doc) => {  const ctx = await mutationCtx(baseCtx);  const user = await ctx.table("users").getX(doc._id);  const numMessages = (await user.edge("messages")).length;  if (numMessages > 10) {  await user.patch({ name: user.name + " Pro" });  }  },  batchSize: 10, });

Dry run your migration

You can execute the migration from code and from the CLI or the dashboard:

npx convex run migrations:myMigration '{"dryRun": true, "fn": "migrations:simpleMigration"}' # --prod

See the Stack article (opens in a new tab) for other ways of running your migrations.

Examples

There is an example migrations file here: migrations.ts (opens in a new tab).

Testing Ents Project Status