Create a branch

Cut a masked, writable copy of a database in seconds, connect to it, and delete it when you are done.

Last updated 18 November 2026View as Markdown

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:CreateDBBranch on the database; rds:DescribeDBBranches to see the Branches tab and list branches; rds:GetDBBranchCredentials to read the branch's passwords; rds:ModifyDBBranch to change its lifetime and rds:DeleteDBBranch to 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:DescribeDBInstances to open the database's page (without it the page is not found).

Create the branch

  1. Open the database, then choose Branches.
  2. Under New branch, for Name, enter alice-test (lowercase letters, digits and dashes, up to 40 characters).
  3. (Optional) For Point in time (UTC, optional), enter the moment to branch from, to the second.
  4. (Optional) For Lifetime, choose 1 day, 3 days, 7 days (the default) or 30 days.
  5. Choose Create branch.

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

  1. On the Branches tab, open the branch's actions menu and choose Show DATABASE_URL. It is available once the branch is available.
  2. Copy the DATABASE_URL shown below the list of branches. It contains the master user's password.

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=require

Every 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

  1. On the Branches tab, open the branch's actions menu and choose Delete.
  2. In Delete the branch “alice-test”?, choose Delete.

The console does not change a branch's lifetime; use the CLI, the API or Terraform.

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.

Did this page help you?