Migrations

Learn how to change your schema while older clients keep working.
Before your first schema change

You don't need migrations to get a first app running. Read this page before you change a schema that has been deployed: a schema change with no migration leaves the backend refusing to start, and recovering means rebuilding the old schema from your Git history.

Why Jazz migrations are different

Most migration systems are one-way: rewrite every row to the new shape, then cut over. That assumes you can stop the world long enough to upgrade — which doesn't hold when your clients are local-first, frequently offline, and updating their app on their own schedule.

Jazz keeps every schema version usable and translates rows between them on read and write. Clients on different versions stay interoperable, and nothing on disk is rewritten when you ship a new schema.

Schemas and lenses

Every unique version of your schema (the tables in schema.ts) has a hash which can be used to refer to it. When creating migrations, you describe the changes required to move between two schema versions. This is known as a 'lens'. Fetching all intermediate lenses allows clients with any published schema version to read data created with any other published schema version.

Choose data from the left, then pick a schema version on the client device. The row is loaded as-is, and the client applies all the lenses needed to interpret it using its schema.

Data
Schemas + lenses
Client
Schema v1
a01f5c
title: s.string()
Schema v2
311995
title: s.string() completed: s.boolean()
Schema v3
73b65d
title: s.string() done: s.boolean()
Add 'completed', default false
Rename 'completed' to 'done'
Schema:
My To Dos
JSON
{ "title": "Buy milk", "done": false }
v1 row, read through the lens chain by a client on schema v3.

Rows retain the physical schema identity under which they were written. A read in another compatible schema uses lenses to project those rows into the requested shape. Non-adjacent reads compose lenses in sequence to bridge multiple schema versions.

In practice, this lets you:

  • Ship a schema change without waiting for every user to update their app.
  • Roll out platform-by-platform (mobile, desktop, web) on independent cadences.
  • Accept writes from clients that have been offline since before the new schema landed.

Where migrations live

Migrations live in a migrations/ directory next to schema.ts:

  • migrations/*.ts holds the lenses, one file per migration, each a m.defineMigration(...) that goes from one version to another. migrations create writes them; you review and edit them.
  • migrations/snapshots/*.json holds a snapshot of each schema version, named by its short schema hash (the first 12 hex characters). The tool writes them; don't edit them.

npx jazz-tools generate reads both and writes them into jazz.app.json, next to the current tables: history holds the earlier versions your app still ships, oldest first, and migrations the lenses between them. jazz.generated.ts embeds every version and every lens, so clients can read and write data from any version, including before they first sync, and a client never has to rename or reshape stored data later.

Workflow

  1. If this is the first migration you are creating, run:

    npx jazz-tools migrations create

    This creates an initial snapshot of your schema in migrations/snapshots/. No migration file is created yet because there is no previous schema to diff against. Until then your app has no earlier version, and no change needs a migration.

  2. Edit schema.ts — change the data shape as needed.

  3. Run npx jazz-tools generate. If the change touches a schema the bindings were generated from, it refuses before it writes anything:

    the schema changed since the last version: run `jazz-tools migrations create --name <name>`
  4. Create the migration — run:

    npx jazz-tools migrations create --name <your-migration-name>

    Jazz diffs the latest snapshot in migrations/snapshots/ against the current schema.ts, writes a migration file into migrations/, guessing what the diff allows, and saves a snapshot of the new schema. Where only you can decide, it writes a "TODO: …" string instead and lists each one.

  5. Review and resolve — read the migration, and replace every "TODO: …" with what it asks for (see below). generate and every loader refuse a migration with a TODO left, so a half-written migration can't be deployed. Then run npx jazz-tools generate (and your type checker).

  6. Deploy your main backend — restart it locally, or deploy it as usual. When it starts, createJazz sends the schema, permissions and migrations your code imports to its store as one bundle. There is no separate deploy or push command. If the bundle has no migration path from the schema already in the store, the store refuses it with an error naming the missing migration: jazz.ready() rejects with it, and Jazz's routes answer 503 and log it. In development (NODE_ENV=development) the 503 carries the error too, so the browser console shows it. Call await jazz.ready() at startup if you want a refused bundle to stop the process. First deployments and permission-only changes need no migration.

    With several instances, roll out to one first and check it starts before replacing the rest, and keep the previous version ready to roll back to.

    Each deployment's sessions run under that deployment's own bundle, so two deployments can run side by side, and rolling back your backend rolls back its permissions too.

    Browser tabs opened before the deploy keep running the old app and its schema until they reload; Jazz has no reload prompt yet, so add your own if you need one. Serve index.html with Cache-Control: no-cache, or browsers can keep loading the old bundle even after a reload.

The jazz-tools CLI only writes and checks migrations (migrations create, generate, migrations graph). It never publishes anything: only your main backend does.

Commit schema.ts, the migrations/ directory (snapshots included), and the files generate writes (jazz.app.json, jazz.permissions.json and jazz.generated.ts) together. Two branches that each added a migration from the same version add separate migration files, but both change the generated files: keep both branches' migration files and snapshots when you merge, take either side of the generated files, and run npx jazz-tools generate to write them again. Then see Handling concurrent migrations.

Changes that keep every row

Single-column indexes (.indexOnly([...])) aren't part of the schema version, so an edit that only adds, removes or changes them needs no migration: generate writes new bindings. If you run migrations create anyway, it writes nothing and says "only single-column indexes changed: no migration needed; run jazz-tools generate".

Composite indexes (.compositeIndex([...])), .history("latest"), a column's .merge(...) and the column order are part of the schema version, so generate asks for a migration. Run migrations create as usual: it writes an empty step, with nothing to decide, for example for a composite index:

migrate: {
tasks: {
// Rows pass unchanged: only indexes changed.
},
},

Computed fields aren't stored, so adding or changing one needs no migration.

Permission-only changes in definePermissions don't need a migration; they go live when your main backend restarts with them. See Declarative Permissions for details.

The migration file

A migration describes the diff as declarative operations which carry enough information to run in either direction. That is how older clients can still read data written under a newer schema: the same operations replay in reverse.

A generated migration

Say the todos table gains an optional description column. migrations create --name add-description writes:

migrations/20260318T101500-add-description-e5628c8e53c8-311995e9a178.ts
import { schema as s, migration as m } from "jazz-tools";
​
export default m.defineMigration({
migrate: {
todos: {
description: m.add.string({ default: null }),
},
},
fromHash: "e5628c8e53c8",
toHash: "311995e9a178",
from: {
todos: s.table({
title: s.string(),
done: s.boolean(),
}),
},
to: {
todos: s.table({
title: s.string(),
done: s.boolean(),
description: s.string().optional(),
}),
},
});

from and to hold the affected tables of both versions, as the tool wrote them; leave them as they are. default is the value rows written under the older schema read for the new column. The added type carries no .optional(): a lens carries no nullability, and to says whether the column is optional.

What it can't decide

migrations create leaves a TODO wherever the diff alone doesn't say what you meant:

  • A possible rename. An added column shaped like a removed one may be the same column renamed. Adding one and dropping the other would start every row empty, so it asks:

    rank: "TODO: added column `rank` may be a rename of `priority`. To keep its values, replace this with m.renameFrom(\"priority\"); to start it empty, with m.add.int({ default: null }).",

    The removed column gets a matching TODO: delete it if the column was renamed, or replace it with its m.drop.

  • A new required column. Rows written under the older schema need a value for it:

    status: m.add.enum(["todo", "done"], {
    default: "TODO: added required column `status` needs the value existing rows get; replace this with it.",
    }),
  • A dropped required column. Clients still on the older schema need a value to read back (backwardsDefault).

When you run generate with a TODO left, it names each one with its file and path:

migrations/20260318T101500-add-status-311995e9a178-9b2f0c41d7aa.ts: 1 unresolved TODO left by `jazz-tools migrations create`; replace each with the value it asks for, …
migrate.todos.status.default: TODO: added required column `status` needs the value existing rows get; replace this with it.

Customising defaults

Review generated defaults before you publish. For example, you might replace a null default with a domain-specific value:

description: m.add.string({ default: "No description yet" }),

Backwards defaults

When a newer schema drops a column that older clients still expect, give it a backwards default so the lens can supply a value for those clients:

priority: m.drop.int({ backwardsDefault: 0 }),

Operations

A migration's migrate maps each changed table to its column operations; tables themselves are added, dropped and renamed next to it:

migrations/20260401T090000-rename-and-split-3fa1c2d9e0b4-8c7d21a0f6e3.ts
import { migration as m } from "jazz-tools";
​
export default m.defineMigration({
migrate: {
todos: {
notes: m.renameFrom("description"), // same type, new name
priority: m.add.int({ default: 0 }), // a new column and its value for old rows
legacy_flag: m.drop.boolean({ backwardsDefault: false }), // what older clients read
},
},
renameTables: { projects: m.renameTableFrom("lists") },
createTables: { labels: true },
dropTables: { archived_todos: true },
// fromHash, toHash, from and to as generated
});
  • m.add.<type>({ default }) adds a column (string, int, bigint, boolean, timestamp and the other column types). The default fills it for rows written under the older schema.
  • m.drop.<type>({ backwardsDefault }) drops a column; older clients read backwardsDefault.
  • m.renameFrom("oldName") renames a column of the same type. Values carry over.
  • renameTables (newName: m.renameTableFrom("oldName")), createTables and dropTables cover tables that exist on only one side.
  • // comments say why, anywhere in the file.

generate rejects a migration that doesn't cover every change, or that fails the lens checks a deployment runs.

Adding enum variants

An enum column, or an array of enums, can gain variants at the end of its list. Rows written under the older schema hold only variants the new one still declares, so they read unchanged and sort as before, and the migration needs no step. A variant's position in the list is its sort order, so adding one elsewhere, or reordering the list, is refused. jazz-tools migrations create writes a migration with nothing to fill in, noting which column gains which variants:

migrations/20261113T120000-add-blocked-status-d18686fe548a-5e0b3c9a7f12.ts
import { migration as m } from "jazz-tools";
​
export default m.defineMigration({
migrate: {
tasks: {
// Column "status" gains enum variant "blocked": existing rows are unchanged, so it needs no step.
},
},
// fromHash, toHash, from and to as generated
});

Clients still on the older schema read a row holding the new variant with its name as it is (here "blocked"), even though their own types don't list it, so handle unknown values where they read the column. Their own writes are still checked against the variants their schema declares: an older client can't write "blocked".

Changes that aren't supported yet

  • Renaming, removing or reordering enum variants. migrations create refuses a variant missing from the new list, or one that moved, and so does a deploy. Adding variants at the end works, as above.
  • Changing a column's type. migrations create refuses it. Adding a column under a new name and dropping the old one works, but it does not carry values over: every row gets the new column's default, with no warning. There is no value-mapping step yet.
  • Making an optional column required. There's no step for it yet, and adding a required column while dropping the optional one resets every row to the default, as above.
  • Moving data between tables. A lens maps one table's rows; it can't copy values into another table.

For these, expand and contract over two releases. First add the new column or table next to the old one, have your app write both, and copy existing values with a backend job. Once every row is copied and no client still needs the old shape, drop the old column in a later release. Keep the copy job in the release before the drop: once a release drops a column, code on that release can no longer read it.

Adding relations to existing UUID columns

To add a relation using an existing ownerId UUID column, declare owner: s.rel("users", "ownerId") in the table's relations (the second argument to s.table) and follow the migration workflow above. Existing UUID values stay unchanged; the migration is an identity step for the table, which preserves row values while making the relation available under the new schema.

Handling concurrent migrations

When working on real apps, it's normal for multiple devs (or agents) to create migrations starting from the same schema but branching off in different directions.

For example, suppose your task app has a tasks table with a title column. Alice adds a dueDate column while Bob independently adds priority, both starting from the original schema:

Original tasks
├──add dueDate───→ Tasks with due dates (Alice's backend)
└──add priority──→ Tasks with priorities (Bob's backend)

Each deployment publishes its own bundle and its sessions run under it, so Alice's and Bob's backends (two preview deployments, say) can both serve the same data side by side. Nothing on the server becomes "current", and neither deployment blocks the other. A bundle's migration history must have a single root, which both branches share here.

Reading across the branches has a cost, though. Jazz reads a row written under another schema by applying lenses backwards to the common ancestor and forwards again, and that route can discard values. A task written with a due date loses that field when read from the priorities schema, and adding dueDate again later along that route supplies a default instead of the task's original due date.

So while both branches run, each side sees the other's rows without the other's new column. When you're ready to ship, pick one branch or converge both into a merged schema.

Picking one branch

To leave Alice's due-date change behind, deploy Bob's backend and stop deploying Alice's. Rolling back works the same way: redeploy older code, and its sessions run under its own bundle again. No reverse migration is needed, and you shouldn't write one: it would create a cycle, which your main backend rejects on start.

Converging into a merged schema

To preserve both changes, merge both branches' migration files and snapshots, and edit schema.ts so tasks contains both dueDate and priority. Then write a migration into this merged schema from each branch's version:

┌──→ Due dates ──add priority──┐
Original tasks ┤ ├──→ Due dates + priorities
└──→ Priorities ──add dueDate──┘

migrations create only writes a migration from the latest snapshot, so write the second one by hand, next to it in migrations/, with that branch's version as fromHash and its tables as from. The versions' hashes name the files in migrations/snapshots/, and migrations graph shows them too. Review both migrations:

  • The migration from Alice's schema should preserve dueDate and introduce priority.
  • The migration from Bob's schema should preserve priority and introduce dueDate.

And then deploy your main backend.

Rows written under either branch now read with both columns intact. Jazz validates that alternative forward paths agree on the values and column identities they preserve or introduce.

Visualizing the migration graph

Run jazz-tools migrations graph to see the schemas and migrations. It reads the server's history, so it needs a Jazz Cloud app (deprecated) or a remote() store; against a backend's own sqlite() store it fails with a 404.

npx jazz-tools migrations graph <appId> --server-url <url> --admin-secret <secret>

The graph includes all schemas and migrations present in the server and locally, in migrations/. Schemas and migrations that exist only on the server or only locally are labelled accordingly. The graph also marks the local schema.ts and, with "(latest bundle)", the schema of the bundle your backends published most recently.

Compiling the schema

npx jazz-tools schema compile prints, as JSON, the compiled schema jazz.generated.ts embeds: every version and lens. You don't need it in the normal workflow; it is there for tools that want the engine's form.

npx jazz-tools schema compile
npx jazz-tools schema compile --schema-dir ./packages/app

Flags

FlagDefaultDescription
--name <name>requiredmigrations create: the migration's name
--schema-dir <path>., then ./src and ./src/libDirectory holding schema.ts

There is no --fromHash, --toHash or --migrations-dir: a migration goes from the latest snapshot to the current schema.ts, and lives in migrations/ next to schema.ts.

Next steps

  • Defining Tables — table and column definitions
  • Column Types — full list of available column types
  • App files — the format of the generated jazz.app.json, including history and migrations