# 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](branches.md). 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

**Console**
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**.

**CLI**
```sh
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:09Z
```

The second branch is the database as it was at that second.

**API**
```http
POST /rds/api/instances/ewdb-0123456789ab/branches
{ "name": "alice-test", "ttlHours": 168 }
```

**Terraform**
```hcl
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

**Console**
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.

**CLI**
```sh
dcloud rds branches get-credentials ewbr-0123456789ab
```

The output has every login role's password and a `DATABASE_URL` for the master user.

**API**
```http
GET /rds/api/branches/ewbr-0123456789ab/credentials
```

**Terraform:** not available. 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:

```text
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

**Console**
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.

**CLI**
```sh
dcloud rds branches modify ewbr-0123456789ab --ttl-hours 72
dcloud rds branches delete ewbr-0123456789ab
```

`modify` makes the branch expire 72 hours from now.

**API**
```http
DELETE /rds/api/branches/ewbr-0123456789ab
```

To change the lifetime: `PATCH /rds/api/branches/{branchId}` with `{ "ttlHours": 72 }`.

**Terraform**
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.

## Related

- [Configure masking and pull-request branches](configure-branches.md)
- `rds.branches.create` · `dcloud rds branches create` · `dcloud_db_branch`
