> ## Documentation Index
> Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Switchovers
> Move the primary of a Postgres branch to a replica on demand.
export const PlatformAvailability = ({current, vitess, postgres}) => {
const docsHref = path => {
if (!path) return path;
const normalized = path.startsWith('/') ? path : `/${path}`;
return normalized;
};
const labels = {
vitess: 'Vitess',
postgres: 'Postgres'
};
if (current === 'both') {
return
Vitess and Postgres
;
}
const hasVitess = current === 'vitess' || Boolean(vitess);
const hasPostgres = current === 'postgres' || Boolean(postgres);
const only = !(hasVitess && hasPostgres);
const engines = [];
if (current === 'vitess' || current === 'postgres') engines.push(current);
if (hasVitess && current !== 'vitess') engines.push('vitess');
if (hasPostgres && current !== 'postgres') engines.push('postgres');
return
;
};
## Overview
A switchover moves the primary of a Postgres branch to one of its replicas on demand. The current primary steps down and a replica is promoted in its place, using the same battle-tested mechanism PlanetScale uses for [automatic failovers](/docs/postgres/operations-philosophy). Writes are briefly interrupted (on the order of seconds) while the switch completes.
Switchovers are useful when you want to:
* Verify that your application tolerates a primary change before you depend on it during an unplanned failover
* Move the primary ahead of planned work, instead of waiting for routine maintenance to switch over the primary for you
A branch without replicas has nothing to promote. Requesting a switchover on a single-node branch **restarts the instance in place** instead, and the branch is unreachable while it comes back. Check the `method` field on the switchover (`switchover` or `restart`) to see which one a branch got.
## Start a switchover
A branch accepts one switchover at a time. You can start one from the dashboard, the CLI, or the API.
### Dashboard
On the branch page, open the cluster actions menu (the kebab icon next to the cluster summary) and select **Switch over to replica**. On a single-node branch the action reads **Restart cluster** instead.
### CLI
```bash theme={null}
pscale branch switchover $DATABASE $BRANCH
```
### API
```bash theme={null}
curl -X POST \
"https://api.planetscale.com/v1/organizations/$ORG/databases/$DATABASE/branches/$BRANCH/switchovers" \
-H "Authorization: $API_TOKEN"
```
See the [create switchover API reference](/docs/api/reference/create_switchover) for details.
## Choose the replica to promote
By default, an eligible replica is selected automatically. To pick one yourself, first find replica names with `pscale branch infra $DATABASE $BRANCH` or on the branch page in the dashboard, then pass the exact replica `name` as the candidate:
```bash theme={null}
pscale branch switchover $DATABASE $BRANCH --candidate $REPLICA_NAME
```
```bash theme={null}
curl -X POST \
"https://api.planetscale.com/v1/organizations/$ORG/databases/$DATABASE/branches/$BRANCH/switchovers" \
-H "Authorization: $API_TOKEN" \
-d '{"candidate": "$REPLICA_NAME"}'
```
A candidate can only be specified for a branch with replicas.
## Track the outcome
A switchover moves through `pending`, `running`, and a terminal state of `succeeded` or `failed`. List or fetch switchovers via the API:
```bash theme={null}
curl "https://api.planetscale.com/v1/organizations/$ORG/databases/$DATABASE/branches/$BRANCH/switchovers" \
-H "Authorization: $API_TOKEN"
```
A switchover that ends in the `failed` state has an **unconfirmed outcome**: the primary may still have moved, and nothing is rolled back. Check which instance is currently primary (with `pscale branch infra` or the dashboard) before retrying.
## Need help?
Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join our [Discord community](https://pscale.link/community) to see how others are using PlanetScale.