rds.branches.list

A database's branches with where to connect, and its branch pool: machine, base age, masking, operation, space per branch

GET /rds/api/instances/{id}/branchesIAM rds:DescribeDBBranchesRead

Request syntax

GET /rds/api/instances/{id}/branches

Path parameters

  • idRequired

    string

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

Query parameters

  • includeDeletedOptional

    enum

    Include deleted branches

    One of: true, false

Response

200 with pool (null before the first branch: status, host, baseRestoredAt, maskedAt, staleAfterHours, refreshDue, operation, usage, …) and branches, each as `get` describes it.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Fields of data

  • poolAlways

    object, may be null

    The branch pool; null before the first branch
  • pool.​idAlways

    string

    Branch pool id
  • pool.​statusAlways

    one of building, preparing, available, refreshing, deleting, failed

    State of the pool
  • pool.​hostAlways

    object, may be null

    The machine the branches run on; null before it exists
  • pool.​host.​dbInstanceIdAlways

    string

    Database id of the pool machine
  • pool.​host.​identifierAlways

    string

    Its name
  • pool.​host.​instanceClassAlways

    string

    Its instance type
  • pool.​host.​allocatedStorageGibAlways

    number

    Its storage, GiB
  • pool.​host.​statusAlways

    string

    Its state
  • pool.​baseRestoredAtAlways

    string, may be null

    The moment the base's data is from
  • pool.​maskedAtAlways

    string, may be null

    When the base was masked
  • pool.​maskRulesCurrentAlways

    boolean

    False when the masking rules changed since: the next branch refreshes the base
  • pool.​staleAfterHoursAlways

    number

    A branch asked for on an older base refreshes it first; 0: always
  • pool.​refreshDueAlways

    string, may be null

    Why the next branch will refresh the base first; null when it will not
  • pool.​operationAlways

    object, may be null

    The pool's operation in progress; null: none
  • pool.​operation.​idAlways

    string

    Operation id
  • pool.​operation.​kindAlways

    one of prepare-base, refresh-base

    What is being done
  • pool.​operation.​statusAlways

    one of pending, running

    Waiting or running
  • pool.​operation.​requestedAtAlways

    string

    When it was asked for
  • pool.​operation.​claimedAtWhen present

    string

    When the pool machine took it up
  • pool.​operation.​attemptsAlways

    number

    Tries so far
  • pool.​operation.​rulesHashWhen present

    string, may be null

    Fingerprint of the masking rules the base is masked with
  • pool.​usageAlways

    object, may be null

    Space, as the pool machine last reported; null: not reported
  • pool.​usage.​poolSizeBytesAlways

    number

    Size of the pool storage, bytes
  • pool.​usage.​poolFreeBytesAlways

    number

    Free, bytes
  • pool.​usage.​baseUsedBytesAlways

    number

    Taken by the base, bytes
  • pool.​usage.​branchesAlways

    array of object

    Each branch
  • pool.​usage.​branches[].​idAlways

    string

    Branch id
  • pool.​usage.​branches[].​usedBytesAlways

    number

    Bytes written since the clone
  • pool.​usage.​branches[].​runningAlways

    boolean

    Whether its server runs
  • pool.​usageReportedAtAlways

    string, may be null

    When usage was reported
  • pool.​lastErrorAlways

    string, may be null

    Why the pool last failed; null otherwise
  • pool.​emptySinceAlways

    string, may be null

    Since when the pool holds no branch; null while it holds some
  • branchesAlways

    array of object

    The branches of the database
  • branches[].​idAlways

    string

    Branch id (ewbr-…)
  • branches[].​parentDbInstanceIdAlways

    string

    Database the branch is of
  • branches[].​nameAlways

    string

    Branch name
  • branches[].​statusAlways

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

    State of the branch
  • branches[].​originAlways

    one of base, time

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

    string, may be null

    The moment asked for, for origin time
  • branches[].​dataAsOfAlways

    string, may be null

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

    boolean

    Whether masking rules were applied to its data
  • branches[].​maskRuleCountAlways

    number

    Masking rules applied
  • branches[].​expiresAtAlways

    string, may be null

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

    one of api, pull_request

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

    object, may be null

    The pull request it was made for; null otherwise
  • branches[].​pullRequest.​gitRepositoryIdAlways

    string

    Git repository
  • branches[].​pullRequest.​numberAlways

    number

    Pull request number
  • branches[].​connectionAlways

    object

    Where to connect
  • branches[].​connection.​hostAlways

    string, may be null

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

    number, may be null

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

    string

    Database to connect to
  • branches[].​connection.​userAlways

    string

    The master user of the parent database
  • branches[].​connection.​secretNameAlways

    string

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

    string, may be null

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

    number, may be null

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

    string, may be null

    Why it failed; null otherwise
  • branches[].​requestedAtAlways

    string

    When it was asked for
  • branches[].​availableAtAlways

    string, may be null

    When it became available
  • branches[].​createTookMsAlways

    number, may be null

    Request to available, milliseconds
  • branches[].​agentTookMsAlways

    number, may be null

    Time the branch machine spent creating it, milliseconds

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:DescribeDBBranches 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 list id

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_rds_branches_list.