# Branches

A branch is a masked copy-on-write copy of a database that you can write to without touching the original.

Use a branch for a pull request, a preview environment, a migration rehearsal or a bug you want to
reproduce on real data. Branches are **copy-on-write**: once the database's branch pool exists, a
branch takes seconds whatever the size of the database, and it only takes the space of what is
written to it. **Masking rules** replace sensitive columns before anyone can connect to a branch,
and every branch has its own passwords.

## How it works

The first branch of a database builds its **branch pool**: one extra machine (shown on the
database's **Branches** tab under **Branch pool**, and in the database list as
`<name>-branches`) whose data volume is formatted with ZFS, and opened with LUKS when the
database's volumes are encrypted. The pool restores the database's latest completed backup (the
**base**), applies the masking rules to it once, gives the base's master user a new password and
removes the password of every other login role on the base.

A branch is a ZFS snapshot and clone of the base, served by its own PostgreSQL server on its own
port of the pool machine (6500–6519). Nothing is copied: the branch shares every unchanged block
with the base.

| What you ask for                                           | What happens                                                                              | How long                                 |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------- |
| The first branch of a database                             | The pool machine is built from the latest backup, masked, then the branch is cut          | Like a restore: minutes, grows with size |
| A branch (the pool exists)                                 | Clone of the base, own server, new passwords                                              | Seconds, whatever the size               |
| A branch at a point in time                                | The pool restores the backups to that second into a new dataset, masks it, serves it      | Minutes, grows with size and WAL         |
| A branch when the base is stale or masked with older rules | The pool restores the latest backup into a new base first (existing branches keep theirs) | Minutes, then seconds                    |

## How fresh the data is

The base is as fresh as its last restore: **Base data from** on the **Branches** tab
(`baseRestoredAt` in `rds.branches.list`); each branch shows when its data is from (`dataAsOf`,
**Data from**). A branch asked for on a base older than the pool's `staleAfterHours` (default 24;
0 means always) refreshes the base first; so does a change of the masking rules. A point-in-time
branch never waits for a refresh: it restores its own data.

Set `staleAfterHours` with `rds.branches.set-pool`
(`dcloud rds branches set-pool <id> --stale-after-hours 12`, 0 to 720), and refresh the base now
with `rds.branches.refresh-pool` (`dcloud rds branches refresh-pool <id>`, or **Refresh base
now** on the **Branches** tab). Both need `rds:ModifyDBBranchSettings`. Before the first branch
they are refused with `This database has no branch pool yet.` (404); a refresh while the pool is
busy is refused with `The branch pool is <status>.` (409).

## Passwords

Every login role of the database exists on the branch with the same grants, under a **new
password** filed in Secrets as `PG_<DATABASE>_BRANCH_<BRANCH>` (the database's and the branch's
names in capitals, other characters as `_`; a JSON object, role → password). The database's own
passwords never work on a branch. The platform's own roles get no password on a branch.

## Limits

- The number of branches per database is a quota (see [Quotas](quotas.md)). One pool serves at
  most 20 at a time (ports 6500–6519); beyond that a branch is refused (409) with the oldest branch
  named.
- A branch has no connection pooler and no backups; it is a scratch copy. Its server allows 50
  connections and has 128 MB of shared buffers.
- The pool machine is a `performance-4` (4 vCPU, 8 GB) with a disk 1.5× the database's (at least 40 GiB).
- A point-in-time branch can reach back as far as the database's oldest retained backup.
- A branch you create lives 7 days unless you set another lifetime, at most 30 days (720 hours). A
  pull-request branch has no lifetime: it lives as long as its pull request.
- The pool is deleted 24 h after its last branch is gone, and with its database.

## Pricing

The pool machine is a database of its own (`<name>-branches`) and is billed as one of its class
plus its volume, for as long as it exists.

## Related

- [Create a branch](create-a-branch.md)
- [Configure masking and pull-request branches](configure-branches.md)
- [What runs on your machines](what-runs-on-your-machines.md)
