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

# Read replicas

> Add up to 5 read-only copies of a Dedicated database and send read traffic to them through one read address.

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

## Goal

Take read load off the primary for reports, search or heavy dashboards.

## Prerequisites

* A Dedicated database

## Workflow

**Step 1**

Add a replica with `stackshift database replica-add DATABASE` (`POST /api/v1/databases/{id}/replicas`). Pass `--data '{"instance_class":"s-2vcpu-4gb"}'` to choose a size; each replica needs at least half the primary’s memory.

**Step 2**

If the answer is `409 price_confirmation_required`, resend the same request with `confirm_charge_minor` set to the quoted charge.

**Step 3**

Wait until `stackshift database ha DATABASE` shows the replica healthy.

**Step 4**

Point read-only queries at the read address `db-<id>-ro.stackshift.internal`. It answers with every replica that has caught up.

**Step 5**

Remove a replica with `stackshift database replica-remove DATABASE REPLICA`, using the replica id from `stackshift database ha DATABASE`. Its unused time is credited to your wallet.

## Things to know

* Replicas are a little behind the primary. Read your own writes from the primary when it matters.
* A replica that falls too far behind leaves the read address until it catches up.
* `stackshift database ha DATABASE` shows each member’s `lag_seconds`, and the database metrics chart one line per replica over 1, 6 or 24 hours. You get a warning event when a replica is more than 30 seconds behind, and it clears once every replica is under 5 seconds.
* Each replica is billed like a database of its size; adding one asks you to confirm the price.

## 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]
>
> Read queries run on the replicas, and writes keep going to the primary.

## Common failures

> [!WARNING]
>
> * More than 5 replicas, or a replica size smaller than half the primary’s memory, is refused.
> * `409 price_confirmation_required`: resend with `confirm_charge_minor` set to the quoted charge.

## Related guides

> **[Standby and high availability](https://docs.stackshift.cloud/databases/standby-and-high-availability.md)**
>
> Add a standby on another server. If the primary fails, the standby takes over and your connection address stays the same.

> **[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.


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