Create a branch
Cut a masked, writable copy of a database in seconds, connect to it, and delete it when you are done.
How branches work, and what they cost, is in Branches. Replace ewdb-0123456789ab with your database's id, alice-test with the branch's name and ewbr-0123456789ab with the branch's id.
Important
The first branch of a database builds its branch pool, a machine billed as a database of its class plus its volume until 24 hours after its last branch is gone.
Prerequisites
- Permission for
rds:CreateDBBranchon the database;rds:DescribeDBBranchesto see the Branches tab and list branches;rds:GetDBBranchCredentialsto read the branch's passwords;rds:ModifyDBBranchto change its lifetime andrds:DeleteDBBranchto delete it. - The database is available (or backing up, or being modified) and has at least one completed backup.
- For a branch at a point in time, a moment covered by the database's retained backups.
- In the console, also
rds:DescribeDBInstancesto open the database's page (without it the page is not found).
Create the branch
- Open the database, then choose Branches.
- Under New branch, for Name, enter alice-test (lowercase letters, digits and dashes, up to 40 characters).
- (Optional) For Point in time (UTC, optional), enter the moment to branch from, to the second.
- (Optional) For Lifetime, choose 1 day, 3 days, 7 days (the default) or 30 days.
- Choose Create branch.
dcloud rds branches create ewdb-0123456789ab --name alice-test
dcloud rds branches create ewdb-0123456789ab --name before-incident \
--recovery-target-time 2026-11-13T04:12:09ZThe second branch is the database as it was at that second.
POST /rds/api/instances/ewdb-0123456789ab/branches
{ "name": "alice-test", "ttlHours": 168 }resource "dcloud_db_branch" "alice_test" {
db_instance_id = dcloud_db_instance.orders.id
name = "alice-test"
ttl_hours = 72
}A branch lives 7 days (168 hours) unless you set another lifetime, from 1 hour to 30 days (720
hours). The request is accepted (202) and the branch starts as queued (while the pool is built or
its base refreshed) or creating, then becomes available; the first branch's response says the
pool is being built. The Branches tab and dcloud rds branches list <id> show the branches,
the pool and the operation it is running.
The request is refused when:
| Status | Message |
|---|---|
| 409 | <database> is <status>; branches are cut from a running database. |
| 409 | <database> has no completed backup yet; a branch pool is built from one. Try again after the first backup. |
| 409 | <database> already has a branch named <name>. |
| 409 | The database's branch quota is reached, or its pool already serves 20 branches (the message names the oldest). |
| 400 | Nothing was kept for <time>: the oldest retained backup finished at <time>. |
| 400 | A branch cannot be cut from the future. |
Connect to the branch
- On the Branches tab, open the branch's actions menu and choose Show DATABASE_URL. It is
available once the branch is
available. - Copy the DATABASE_URL shown below the list of branches. It contains the master user's password.
dcloud rds branches get-credentials ewbr-0123456789abThe output has every login role's password and a DATABASE_URL for the master user.
GET /rds/api/branches/ewbr-0123456789ab/credentialsNot available in Terraform. Credentials are read, not configured.
Before the branch is available, reading its credentials is refused with
The branch is <status>; it has no credentials yet. (409).
A branch is reached at the pool machine's address and the branch's own port, over TLS
(sslmode=require), as the database's master user and its database:
postgres://admin:<password>@<pool endpoint>:6503/appdb?sslmode=requireEvery login role of the database exists on the branch under a new password, filed in Secrets as
PG_<DATABASE>_BRANCH_<BRANCH>. The database's own passwords never work on a branch. Reading the
credentials is a sensitive read: it is recorded in the audit log and in the database's
Activity.
Change the lifetime or delete the branch
- On the Branches tab, open the branch's actions menu and choose Delete.
- In Delete the branch “alice-test”?, choose Delete.
The console does not change a branch's lifetime; use the CLI, the API or Terraform.
dcloud rds branches modify ewbr-0123456789ab --ttl-hours 72
dcloud rds branches delete ewbr-0123456789abmodify makes the branch expire 72 hours from now.
DELETE /rds/api/branches/ewbr-0123456789abTo change the lifetime: PATCH /rds/api/branches/{branchId} with { "ttlHours": 72 }.
Change ttl_hours, or remove the dcloud_db_branch resource and run terraform apply.
A pull-request branch's lifetime cannot be changed: modify is refused with
A pull-request branch lives as long as its pull request. (409). A delete is accepted (202): the
branch goes to deleting, its server stops, and its passwords are removed from Secrets. A branch
still queued is deleted at once.
Result
A branch on an existing pool serves in seconds, whatever the size of the database; the first branch, or one at a point in time, takes minutes. Activity records every step: pool built, base masked (with the rules skipped), branch requested, branch available with how long it took, deleted, expired. Deleting a branch removes what was written to it; the database itself is not touched.