Skip to main content
Branches are in beta.
A branch is a fork of your deployment at one exact moment. It starts with the data live had at that moment, and then records its own changes. Nothing you do on a branch reaches live, and nothing that happens on live afterwards reaches the branch. Use a branch to ask “what if?” against real data: change a price, delete a record, or run a new version of your functions, then look at what your queries return. When you like the result, apply it to live. When you don’t, discard it.
Creating a branch copies no data. The branch loads the first time you use it.

​
What a branch is

A branch has three parts:
  • An exact parent basis. The branch is a fork of live (your deployment’s current data) or of an empty deployment. It is pinned to the parent’s revision at the moment you created it, and it reads every inherited document exactly as it was at that revision. Later writes to live are invisible to the branch.
  • Its own changes. Everything written on the branch is stored on the branch. Live never sees it. Your queries on the branch read one database: the inherited documents plus the branch’s own writes, including in index range reads.
  • Explicit absence. Deleting an inherited document on the branch hides it from every read on the branch. Live keeps the document.
Because a branch is its own deployment instance, the same apps and the same CLI work against it. You point them at the branch’s URL instead of live’s. See working with branches.

​
Nothing leaves a branch

A branch is created with every channel to the outside closed: When an integration command declares the change it makes, a held call to it shows on the branch as an assumed result, so you can see its consequences. An assumed result never leaves the branch. Data leaves a branch in exactly one way: applying re-runs the operations you invoked on the branch against live, under live’s current data and your current permissions. Rows are never copied.

​
Lifecycle

1

Create

Fork live, or an empty deployment. See creating a branch.
2

Work and share

Deploy code, run functions and invoke operations against the branch URL. Share it with users who should see it.
3

Compare

Run a query on the branch and on live at the branch’s basis, and see which rows were added, removed or changed.
4

Finish

Apply your operations to live, rebase them onto a fresh fork, or discard the branch. A branch you leave alone expires.

Working with branches

Create, open, share, compare, extend and discard a branch.

Apply and rebase

Replay your branch operations onto live or onto a fresh fork.

The Branch page

Manage a branch from the Bijection console.

bijection branch

Every command and flag.

​
Limits

These are not supported yet:
  • Branches of branches. A branch cannot itself be branched. Branch its parent instead.
  • Recorded code refs. A branch does not record which version of your code it runs. Keep track of what you deployed to it yourself.
  • Row-level authority checks against live. Row-level reads on a branch are authorized by the permission records the branch holds: live’s records at the basis, plus any changes made on the branch. A permission revoked on live after the branch was created still applies on the branch until you unshare the user, discard the branch, or it expires. Unsharing takes effect at once, including for open connections. See access rules.
  • Comparing two branches with each other. Compare always reads a branch against its parent.
  • Running a branch forward in time. Scheduled functions and crons run only while the branch is open. See open and closed branches.
Branches also have fixed bounds: While any branch of live is open, your deployment keeps all of its history since the oldest open branch’s basis, not only the documents that branch can see. Creating or extending a branch of live is refused once that history exceeds one million document revisions. Discard branches you no longer need.