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 GET /rds/api/instances/{id}/branches); 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 PATCH /rds/api/instances/{id}/branch-pool
(dcloud rds branches set-pool <id> --stale-after-hours 12, 0 to 720), and refresh the base now
with POST /rds/api/instances/{id}/branch-pool/refresh (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). 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.