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
| Resource | Scopes |
|---|---|
| Organization | write_databases |
| Database | write_database |
Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Path Parameters
Organization name slug from list_organizations. Example: acme.
Database name slug from list_databases. Example: app-db.
Branch name from list_branches. Example: main.
Body
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
The ID of the switchover
The state of the switchover
pending, running, succeeded, failed, canceled When the switchover was requested
When the switchover finished
When the switchover was created
When the switchover was last updated
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.
switchover, restart Why the switchover failed. A failed switchover has an unconfirmed outcome and does not imply the primary stayed put.

