> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Standby and high availability

> Add a standby on another server. If the primary fails, the standby takes over and your connection address stays the same.

> [!NOTE]
>
> **Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

## Goal

Keep your database available through a server failure.

## Prerequisites

* A Dedicated PostgreSQL database
* High availability switched on for your account

## Workflow

**Step 1**

Choose a mode: `sync` (no committed write is lost) or `async` (faster writes; the last moments of writes can be lost in a failover).

**Step 2**

Turn it on: `stackshift database standby DATABASE --data '{"mode":"sync","on_standby_loss":"degrade"}'` (`PUT /api/v1/databases/{id}/standby`). The database stays online and keeps its address.

**Step 3**

If the answer is `409 price_confirmation_required`, the standby costs extra. Send the same request again with `confirm_charge_minor` set to the quoted charge. If the wallet is short you get `402 payment_required` with a checkout link.

**Step 4**

Check progress with `stackshift database ha DATABASE` until the standby member is healthy.

**Step 5**

Turn it off the same way with `"mode":"off"`. On monthly and yearly billing the unused part of the period is credited to your wallet.

## If the standby is lost

* `on_standby_loss: degrade` (default): writes continue on the primary and you get an alert, until a new standby is ready.
* `on_standby_loss: block`: writes wait until a standby is back, so a sync write is never acknowledged by one server alone.

## Switch to the standby on purpose

To test a failover or move off the current server, switch over yourself with `stackshift database switchover DATABASE` (`POST /api/v1/databases/{id}/switchover`). Send `{"target_id": "<standby id>"}` to pick the standby, or nothing to use the most advanced running one. The old primary becomes the standby. The database keeps its address and drops connections briefly.

It is refused with `409` when there is no standby yet, the chosen member is a read replica, a size change or switchover is already running, or the database is stopped.

## What a failover looks like

Your app keeps the same hostname. Open connections drop and reconnect, so use a driver or pool that retries. Size changes use the same switch, so they also cause only a short pause.

A standby is billed like a second database of the same size. The change asks you to confirm the price first.

`stackshift database ha DATABASE` lists the members (primary, standby, replicas), their status and any size change in progress. Failovers and switchovers also appear in the events feed (`stackshift database events DATABASE`).

## Availability

Dedicated databases are rolling out. If Create doesn’t offer Dedicated, it isn’t switched on for your account yet, and the API answers `403`.

## Expected result

> [!TIP]
>
> The database has a healthy standby on another server and fails over automatically.

## Common failures

> [!WARNING]
>
> * `403` when turning the standby on: high availability isn’t switched on for your account yet.
> * `409 price_confirmation_required`: resend with `confirm_charge_minor` set to the quoted charge.
> * `402 payment_required`: top up your wallet, then retry.
> * `409` while a size change or a switchover is running: wait for it to finish.

## Related guides

> **[Read replicas](https://docs.stackshift.cloud/databases/read-replicas.md)**
>
> Add up to 5 read-only copies of a Dedicated database and send read traffic to them through one read address.

> **[Dedicated databases](https://docs.stackshift.cloud/databases/dedicated-databases.md)**
>
> Create a Dedicated PostgreSQL database, connect to it, resize it and manage its lifecycle.

> **[Performance Insights and events](https://docs.stackshift.cloud/databases/performance-insights-and-events.md)**
>
> See what a Dedicated database spends its time on, find its slowest queries, and read a feed of failovers, backups and maintenance.

> **[Dedicated billing](https://docs.stackshift.cloud/databases/dedicated-billing.md)**
>
> Pay for a Dedicated database monthly, yearly or by the hour, from your wallet or card.

> **[Starter standby](https://docs.stackshift.cloud/databases/starter-standby.md)**
>
> Add a standby to a Starter PostgreSQL database. Redis and Valkey Starter databases can add an asynchronous standby.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.