rds.branches.create

Cut a branch: a ZFS clone of the masked pool base, or a restore to a second

POST /rds/api/instances/{id}/branchesIAM rds:CreateDBBranchChanges state

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

  • idRequired

    string

    Constraints: 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

Request body

  • nameRequired

    string

    Branch name: lowercase letters, digits and dashes (pr-42, alice-test)

    Constraints: 1-40 chars, /^[a-z0-9][a-z0-9-]*$/

  • recoveryTargetTimeOptional

    string

    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)

  • ttlHoursOptional

    number

    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

  • branchAlways

    object

    The branch
  • branch.​idAlways

    string

    Branch id (ewbr-…)
  • branch.​parentDbInstanceIdAlways

    string

    Database the branch is of
  • branch.​nameAlways

    string

    Branch name
  • branch.​statusAlways

    one of queued, creating, available, deleting, deleted, failed

    State of the branch
  • branch.​originAlways

    one of base, time

    base: a clone of the pool's base; time: restored to recoveryTargetTime
  • branch.​recoveryTargetTimeAlways

    string, may be null

    The moment asked for, for origin time
  • branch.​dataAsOfAlways

    string, may be null

    The moment the branch's data is from
  • branch.​maskedAlways

    boolean

    Whether masking rules were applied to its data
  • branch.​maskRuleCountAlways

    number

    Masking rules applied
  • branch.​expiresAtAlways

    string, may be null

    When the branch is deleted; null for a pull-request branch, which lives with its pull request
  • branch.​sourceAlways

    one of api, pull_request

    Asked for through the API or console, or made for a pull request
  • branch.​pullRequestAlways

    object, may be null

    The pull request it was made for; null otherwise
  • branch.​pullRequest.​gitRepositoryIdAlways

    string

    Git repository
  • branch.​pullRequest.​numberAlways

    number

    Pull request number
  • branch.​connectionAlways

    object

    Where to connect
  • branch.​connection.​hostAlways

    string, may be null

    Host to connect to; null until the branch pool has one
  • branch.​connection.​portAlways

    number, may be null

    Port of the branch; null until it is assigned
  • branch.​connection.​databaseAlways

    string

    Database to connect to
  • branch.​connection.​userAlways

    string

    The master user of the parent database
  • branch.​connection.​secretNameAlways

    string

    Secrets entry holding every login role's password on the branch
  • branch.​connection.​urlAlways

    string, may be null

    postgres:// URL without the password; null while host or port is unknown
  • branch.​usedBytesAlways

    number, may be null

    Bytes written to the branch since it was cut, as last reported
  • branch.​errorAlways

    string, may be null

    Why it failed; null otherwise
  • branch.​requestedAtAlways

    string

    When it was asked for
  • branch.​availableAtAlways

    string, may be null

    When it became available
  • branch.​createTookMsAlways

    number, may be null

    Request to available, milliseconds
  • branch.​agentTookMsAlways

    number, may be null

    Time the branch machine spent creating it, milliseconds
  • noteAlways

    string, 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 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.