Anon Keys6

Auth Admin9

Auth Configuration25

Authentication23

Database Backups9

Database Branches7

Database Queries10

Databases10

Durable Functions22

Frontends15

Functions17

Git Connections6

Locks5

Logs3

OAuth Authentication13

OAuth Configuration6

Project Access Tokens6

Project Imports8

Projects27

Realtime3

Sandboxes24

Service Keys5

Storage Admin2

Storage Buckets5

Storage Objects9

Storage Policies3

System6

Variables5

Verified Domains3

Database Branches

Create a branch of a database

Changed on Oct 7, 2026

Forks the database into a new branch. The branch starts as an exact copy of the parent's data and diverges from there.

Provisioning is asynchronous: the response is 202 with the branch in provisioning and no connection string. Poll the branch until it reports active, at which point it carries its own connection string.

Retrying a create with a name that already exists returns 409 rather than a second branch, so a retried request cannot silently consume two slots of the branch allowance.

post/projects/{id}/databases/{databaseName}/branches

Request

Base URL: https://api.volcano.dev
URL: https://api.volcano.dev/projects/{id}/databases/{databaseName}/branches
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)

Request body

namestring required

Branch name (must be unique within the parent database)

ttl_secondsinteger

How long the branch should live, between one hour and 30 days. Defaults to 7 days when omitted.

Example request

{
  "name": "feature_checkout",
  "ttl_seconds": 86400
}

Response

Branch accepted and provisioning

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

Oct 7, 202623e7875e7c4c Revision changes
- ○
  the endpoint scheme security ProjectAccessToken was added to the API
Sep 19, 20263a6f365f3f35 Revision changes
- ▲
  added the new path request parameter databaseName
- ▲
  added the new path request parameter id
- ▲
  added the new required request property
- ▲
  the request's body type changed from no type to object
- ▲
  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
- ▲
  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 new optional request property
- ○
  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 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
- ○
  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

Operation history (3 revisions)