rds.branches.createCut a branch: a ZFS clone of the masked pool base, or a restore to a second
The first branch of a database builds its branch pool (a restore of the latest backup onto one machine, minutes); later ones take seconds. A base older than the pool’s staleAfterHours (24) or masked with other rules is refreshed first. Every login role gets a new password on the branch (get-credentials).
Request syntax
POST /rds/api/instances/{id}/branches
{
"name": "string",
"recoveryTargetTime": "string",
"ttlHours": "number"
}Path parameters
idRequiredstring
Constraints: 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/
Request body
nameRequiredstring
Branch name: lowercase letters, digits and dashes (pr-42, alice-test)
Constraints: 1-40 chars, /^[a-z0-9][a-z0-9-]*$/
recoveryTargetTimeOptionalstring
Branch the database as it was at this second (restored on the pool, minutes); omitted: now, a copy-on-write clone of the pool base (seconds)
ttlHoursOptionalnumber
Hours until the branch is deleted; default 168 (7 days)
Constraints: integer, 1-720
Response
202 with { branch, note }: the branch as `get` describes it, and a note on what happens before it is available (null when nothing is in the way).
A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.
Fields of data
branchAlwaysobject
The branchbranch.idAlwaysstring
Branch id (ewbr-…)branch.parentDbInstanceIdAlwaysstring
Database the branch is ofbranch.nameAlwaysstring
Branch namebranch.statusAlwaysone of queued, creating, available, deleting, deleted, failed
State of the branchbranch.originAlwaysone of base, time
base: a clone of the pool's base; time: restored to recoveryTargetTimebranch.recoveryTargetTimeAlwaysstring, may be null
The moment asked for, for origin timebranch.dataAsOfAlwaysstring, may be null
The moment the branch's data is frombranch.maskedAlwaysboolean
Whether masking rules were applied to its databranch.maskRuleCountAlwaysnumber
Masking rules appliedbranch.expiresAtAlwaysstring, may be null
When the branch is deleted; null for a pull-request branch, which lives with its pull requestbranch.sourceAlwaysone of api, pull_request
Asked for through the API or console, or made for a pull requestbranch.pullRequestAlwaysobject, may be null
The pull request it was made for; null otherwisebranch.pullRequest.gitRepositoryIdAlwaysstring
Git repositorybranch.pullRequest.numberAlwaysnumber
Pull request numberbranch.connectionAlwaysobject
Where to connectbranch.connection.hostAlwaysstring, may be null
Host to connect to; null until the branch pool has onebranch.connection.portAlwaysnumber, may be null
Port of the branch; null until it is assignedbranch.connection.databaseAlwaysstring
Database to connect tobranch.connection.userAlwaysstring
The master user of the parent databasebranch.connection.secretNameAlwaysstring
Secrets entry holding every login role's password on the branchbranch.connection.urlAlwaysstring, may be null
postgres:// URL without the password; null while host or port is unknownbranch.usedBytesAlwaysnumber, may be null
Bytes written to the branch since it was cut, as last reportedbranch.errorAlwaysstring, may be null
Why it failed; null otherwisebranch.requestedAtAlwaysstring
When it was asked forbranch.availableAtAlwaysstring, may be null
When it became availablebranch.createTookMsAlwaysnumber, may be null
Request to available, millisecondsbranch.agentTookMsAlwaysnumber, may be null
Time the branch machine spent creating it, millisecondsnoteAlwaysstring, may be null
What happens before it is available (the pool is built or refreshed first); null: nothing
Checked against the handlers: every route test validates their answers against this schema.
Errors
- 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
- 401No credentials, or an access key that is unknown, revoked or expired.
- 403The caller's policies do not allow rds:CreateDBBranch on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
- 404The resource does not exist in your organization.
Examples
The required parameters only, with example values. Replace id and the other placeholders with your own.
dcloud rds branches create id --name examplecurl -X POST "https://console.platform-development.deutschecloud.app/rds/api/instances/id/branches" \
-H "Authorization: EWS-ACCESS-KEY $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"example"}'Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_rds_branches_create.