Skip to main content

​
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. 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

​
API

See the create switchover API reference 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:
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:
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, or join our Discord community to see how others are using PlanetScale.