Sign in
Database Branches

Get a branch

Changed on

Returns the branch, including its connection string once it is active. Poll this after creating a branch to learn when it is connectable.

get/projects/{id}/databases/{databaseName}/branches/{branchName}

Request

  • Base URL: https://api.volcano.dev
  • URL: https://api.volcano.dev/projects/{id}/databases/{databaseName}/branches/{branchName}
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

idstring uuid required

Project ID

databaseNamestring required

Database name (unique within project, lowercase letters, numbers, and underscores only)

branchNamestring required

Branch name (unique within the parent database, lowercase letters, numbers, and underscores only)

Response

Successful response

idstring uuid required
database_idstring uuid required

The parent database this branch was forked from.

project_idstring uuid required
namestring required

Branch name, unique within the parent database.

status'provisioning' | 'active' | 'failed' | 'deleting' required

Branch status. A new branch starts provisioning and is not connectable until it reports active; poll this endpoint until it does. connection_string is only present while active.

provisioning also covers a branch being rebuilt after a reset, and a build that is between retries, so it is the status to keep waiting on. failed is terminal: it means the platform gave up, and the branch will not become active on its own.

connection_stringstring

PostgreSQL connection URI for this branch. Present only while the branch is active.

The URI carries the branch's own globally-unique username and password; application_name selects the access mode exactly as it does for the parent database:

  • volcano_full_access — Full admin access (DDL, migrations)
  • volcano_user_access:{user_id} — User impersonation (RLS enforced)
  • volcano_user_access — Anonymous access (anon role, RLS enforced)
ttl_secondsinteger required

The lifetime the branch was created with. Resetting a branch re-arms this same duration, so a reset never shortens a branch's remaining life.

expires_atstring date-time required

When the branch stops serving connections and becomes eligible for deletion. Enforced on the connection path, so it holds even if reclamation is delayed.

storage_bytesinteger

Bytes this branch has diverged from its parent, which is what a branch actually costs. Shared pages are not counted twice. Counts against the parent database's storage allowance. Absent until the branch has been sampled.

last_invoked_atstring date-time

Most recent request timestamp for this branch

created_atstring date-time required
updated_atstring date-time required

Changes

  • 23e7875e7c4cRevision changes
    • ○

      the endpoint scheme security ProjectAccessToken was added to the API

  • 3a6f365f3f35Revision changes
    • ▲

      added the new path request parameter branchName

    • ▲

      added the new path request parameter databaseName

    • ▲

      added the new path request parameter id

    • ▲

      the response's body type changed from no type to object for status

    • ▲

      the response's body type changed from no type to object for status

    • ▲

      the response's body type changed from no type to object for status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status