Branches

Every row version in Jazz belongs to a branch — a named, independent view of your data. Some branches are merged automatically at query time (schema versions), while others are fully isolated (environments and user branches). This makes it easy to keep development data separate from production, or to create parallel lines of work like drafts or staging.

How branches are composed

A branch name in Jazz has three parts:

These are joined into a single identifier: dev-a1b2c3d4-main.

The schema hash is derived automatically from your current schema definition.

Configuring branches

By default, Jazz uses env: "dev" and userBranch: "main". To target a different branch, set env and/or userBranch when creating your database context:

export function BranchApp() {
  return (
    <JazzProvider
      config={{
        appId: "my-app",
        env: "prod",
        userBranch: "staging",
      }}
    >
      <TodoApp />
    </JazzProvider>
  );
}

import { createJazzClient, JazzProvider } from "jazz-tools/vue";

const client = createJazzClient({
  appId: "my-app",
  env: "prod",
  userBranch: "staging",
});

import { createJazzClient, JazzSvelteProvider } from 'jazz-tools/svelte';

const client = createJazzClient({
  appId: 'my-app',
  env: 'prod',
  userBranch: 'staging',
});

export async function createBranchDb() {
  return createDb({
    appId: "my-app",
    env: "prod",
    userBranch: "staging",
  });
}

All reads and writes through this context will operate on the prod-{schemaHash}-staging branch. Data on other branches is unaffected.

Schema versions are merged automatically

When your schema changes, Jazz creates a new branch with a different schema hash (e.g. prod-a1b2c3d4-main for v1 and prod-e5f6g7h8-main for v2). At the storage level, data from different schema versions is kept separate.

At query time, Jazz automatically fetches data from all known schema versions within your current environment and user branch. It applies migrations to adapt older data to your current schema automatically.

Environments and user branches are fully isolated

Unlike schema versions, different environments and user branches are never merged. A query on dev-*-main does not include data from prod-*-main, and a query on *-*-staging does not include data from *-*-main. This is hard isolation: there is no way to combine data across environments or user branches at query time.