Sign in
Switchovers

Create a switchover

    Moves the primary of a Postgres branch.

    On a branch with replicas the primary steps down and a replica is
    promoted in its place. A branch running a single instance has nothing to
    promote, so that instance is restarted where it stands and the branch is
    unreachable while it comes back. Read `method` on the response to see
    which one the branch got.

    A branch accepts one switchover at a time. A switchover that ends in the
    `failed` state has an unconfirmed outcome: the primary may still have
    moved, and nothing is rolled back.

Authorization

A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:

Service Token Accesses write_database

OAuth Scopes

ResourceScopes
Organizationwrite_databases
Databasewrite_database
post/organizations/{organization}/databases/{database}/branches/{branch}/switchovers

Path parameters

organizationstring required

Organization name slug from list_organizations. Example: acme.

databasestring required

Database name slug from list_databases. Example: app-db.

branchstring required

Branch name from list_branches. Example: main.

Request body

candidatestring

The exact name of the replica returned by the branch's Postgres infrastructure endpoint to promote. Omit to let the operator select an eligible replica. Only applies to branches with replicas.

Response

Returns the new switchover

idstring required

The ID of the switchover

state'pending' | 'running' | 'succeeded' | 'failed' | 'canceled' required

The state of the switchover

method'switchover' | 'restart' nullable

How the primary was moved. switchover promotes a replica on a highly available branch; restart restarts the single instance of a branch that has no replicas. Absent until the operator selects one.

errorstring nullable

Why the switchover failed. A failed switchover has an unconfirmed outcome and does not imply the primary stayed put.

started_atstring nullable required

When the switchover was requested

completed_atstring nullable required

When the switchover finished

created_atstring required

When the switchover was created

updated_atstring required

When the switchover was last updated

Changes