Read replicas

Read replicas are read-only copies of your database on other servers. They serve REST reads close to your users and take load off the primary.

#Availability

Read replicas are a paid add-on on Pro, Scale and Enterprise; the table shows how many each project can have. Open Read replicas in your project and click Add read replica. It appears with its endpoints as soon as it streams (if a new server has to be prepared first, usually within 15 minutes). On Scale and Enterprise, replicas can also be added automatically when load is high.

#Price

• $0.01 per replica-hour (about $7.30 a month for a replica running all month), plus $0.10 per GB-month for database data above your plan's included database size (the replica's copy of it).
• Paid from your prepaid balance, charged by the minute and debited hourly. A replica starts only when your balance covers 24 hours of it and the month's usage is under your spending cap.
• Click Remove on a replica to stop it; charges stop right away. When your balance runs out or the spending cap is reached, replicas are removed and you get an e-mail; your database keeps working on the primary. Replicas also stop if your plan changes to one without them.

#Automatic replicas

On Scale and Enterprise, the Automatic read replicas card on the Read replicas page adds replicas when load is high and removes them when it drops. Owners and admins set four rules and turn it on:

Load is measured every minute. It is the highest of three values: the CPU use of your primary server, your database connections against your plan's limit, and the CPU use of the servers that already run your replicas. The card shows the current load, CPU and connections, and a chart of the last hour against your two thresholds.

• After adding one, it waits the full "above" time again before it adds another, and does not remove a replica in the "below" time right after adding it.
• It only removes replicas it added. Replicas you added by hand are never touched by the rules.
• Automatic replicas cost the same as the ones you add by hand and follow the same balance and spending cap rules above. If no server has room, a new one is prepared and the replica is added when it is ready; you get an e-mail if that is not possible.

From the API: GET and PUT /platform/projects/<ref>/auto-replicas with { "enabled": true, "up_pct": 70, "up_minutes": 5, "down_pct": 30, "down_minutes": 30, "max_replicas": 2 } (dashboard session; changes need an owner or admin). Every change is written to the audit log.

#High availability

The High availability card on the Read replicas page shows the region of your project's primary server, whether automatic failover is on for it, and the last failover or planned switchover. With automatic failover, a standby server takes over when the primary stops answering; your project keeps its URL, API keys and connection strings. StitchDB turns it on per server.

#How reads are routed

Your project URL https://<project-ref>.p.stitchdb.com is answered by StitchDB's own DNS servers. They send each visitor to the nearest healthy server that has your project: the primary, or a replica when it is clearly closer (more than about 500 km). On a replica server:

• GET and HEAD requests to /rest/v1/ are answered from the replica.
• Everything else (inserts, updates, deletes, POST RPC calls, Auth, Storage and Realtime) is forwarded to the primary over a private network.
• A replica that stops replicating or falls more than 10 seconds behind is taken out of routing automatically.

Responses include an X-StitchDB-Box header naming the server that answered.

#Read endpoint

To send reads to replicas explicitly, use the read-only endpoint. It serves the REST API only:

const reader = createClient('https://<project-ref>-ro.p.stitchdb.com', '<anon-key>')
const { data } = await reader.from('products').select('*')

curl 'https://<project-ref>-ro.p.stitchdb.com/rest/v1/products?select=*' -H "apikey: <anon-key>"

Each replica also has read-only Postgres connection strings (session and transaction mode) on the Read replicas page, together with its replication lag over the last hour.

#Consistency

Replication is asynchronous: a replica can be a moment behind the primary (its lag is shown on the Read replicas page), so a row you just wrote may not be visible on the next read. When a read must see your latest writes, send the header X-Stitch-Read: primary and it is answered by the primary:

// Force one read to the primary (for example right after a write)
const { data } = await stitchdb.from('orders').select('*').eq('id', 42).setHeader('X-Stitch-Read', 'primary')

// Or for every request of a client
const writer = createClient('https://<project-ref>.p.stitchdb.com', '<anon-key>', { global: { headers: { 'X-Stitch-Read': 'primary' } } })

curl 'https://<project-ref>.p.stitchdb.com/rest/v1/orders?id=eq.42' \
  -H "apikey: <anon-key>" \
  -H "X-Stitch-Read: primary"

#Automatic read replicas

On the Scale plan, Read replicas → Automatic read replicas adds replicas when your project is busy and removes them when it is quiet:

• Load is the highest of the primary server's CPU, your connections compared with your plan's limit, and the replicas' CPU.
• Defaults: add a replica when load is above 70% for 5 minutes, remove one when it is below 30% for 30 minutes, at most 2 replicas (your plan's replica limit). You can change all three.
• Automatic replicas cost the same as replicas you add yourself (see Price), paid from your prepaid balance. They count toward your plan's replica limit; the load rule never removes replicas you added yourself.
• A replica only starts when your balance covers at least 24 hours of replicas and the month's usage is under your spending cap. When the balance runs out or the cap is reached, automatic replicas are removed and you get an e-mail; your database keeps working on the primary.
• Replicas added by the StitchDB team count towards the limit and are never removed automatically.