Convex Stateful Migrations Component

Note: Convex Components are currently in beta

Define migrations, like this one setting a default value for users:

// in convex/migrations.ts
export const setDefaultValue = migrations.define({
  table: "users",
  migrateOne: async (ctx, user) => {
    if (user.optionalField === undefined) {
      await ctx.db.patch(user._id, { optionalField: "default" });
    }
  },
});

See below and this article for more information.

Convex App

You'll need a Convex App to use the component. Run npm create convex or follow any of the Convex quickstarts to set one up.

Installation

Install the component package:

npm install @convex-dev/migrations

Create a convex.config.ts file in your app's convex/ folder and install the component by calling use:

// convex/convex.config.js
import { defineApp } from "convex/server";
import migrations from "@convex-dev/migrations/convex.config";

const app = defineApp();
app.use(migrations);

export default app;

Usage

Examples below are assuming the code is in convex/migrations.ts. This is not required.

import { components, internalMutation } from "./_generated/server";
import { defineMigrations } from "@convex-dev/migrations";
import { internal } from "./_generated/api";

export const migrations = new Migrations(components.migrations, {
  internalMutation,
});

The internalMutation argument is optional, but recommended. It provides type safety for your migrations and a way to provide a custom internalMutation if you have database wrappers configured, such as triggers.

Define migrations:

export const setDefaultValue = migrations.define({
  table: "myTable",
  migrateOne: async (ctx, doc) => {
    if (doc.optionalField === undefined) {
      await ctx.db.patch(doc._id, { optionalField: "default" });
    }
  },
});

// Shorthand
export const clearField = migrations.define({
  table: "myTable",
  migrateOne: async (ctx, doc) => ({ optionalField: undefined }),
});

export const validateRequiredField = migrations.define({
  table: "myTable",
  // Specify a custom range to only include documents that need to change.
  // This is useful if you have a large dataset and only a small percentage of
  // documents need to be migrated.
  customRange: (q) =>
    q.withIndex("requiredField", (q) => q.eq("requiredField", "")),
  migrateOne: async (_ctx, doc) => {
    console.log("Needs fixup: " + doc._id);
    // Shorthand for patching
    return { requiredField: "<empty>" };
  },
});

Run it from the CLI by first defining a run function:

// in convex/migrations.ts for example
export const run = migrations.runFromCLI();

// Or define a single runner:
export const runIt = migrations.runFromCLI(internal.migrations.setDefaultValue);

Then run it:

npx convex run migrations:run '{"fn": "migrations:setDefaultValue"}'

# or
npx convex run migrations:runIt

You can also run one or more from a server function:

await migrations.runOne(ctx, internal.example.setDefaultValue);
// Or run a series of migrations in order, e.g. if they depend on each other
// or as part of a post-deploy script:
const allMigrations = [
  internal.migrations.setDefaultValue,
  internal.migrations.validateRequiredField,
  internal.migrations.convertUnionField,
];
await migrations.runSerially(ctx, allMigrations);

See this article for more information on usage and advanced patterns.

🧑‍🏫 What is Convex?

Convex is a hosted backend platform with a built-in database that lets you write your database schema and server functions in TypeScript. Server-side database queries automatically cache and subscribe to data, powering a realtime useQuery hook in our React client. There are also clients for Python, Rust, ReactNative, and Node, as well as a straightforward HTTP API.

The database supports NoSQL-style documents with opt-in schema validation, relationships and custom indexes (including on fields in nested objects).

The query and mutation server functions have transactional, low latency access to the database and leverage our v8 runtime with determinism guardrails to provide the strongest ACID guarantees on the market: immediate consistency, serializable isolation, and automatic conflict resolution via optimistic multi-version concurrency control (OCC / MVCC).

The action server functions have access to external APIs and enable other side-effects and non-determinism in either our optimized v8 runtime or a more flexible node runtime.

Functions can run in the background via scheduling and cron jobs.

Development is cloud-first, with hot reloads for server function editing via the CLI, preview deployments, logging and exception reporting integrations, There is a dashboard UI to browse and edit data, edit environment variables, view logs, run server functions, and more.

There are built-in features for reactive pagination, file storage, reactive text search, vector search, https endpoints (for webhooks), snapshot import/export, streaming import/export, and runtime validation for function arguments and database data.

Everything scales automatically, and it’s free to start.