Read Replicas

Scale read operations with PostgreSQL read replicas.

Overview

Read replicas are read-only copies of your primary database that:

Scale reads - Distribute read queries across replicas
Reduce latency - Place replicas closer to users
Improve availability - Automatic failover when enabled

Read replicas are available on Large tier and above.

Create Read Replica

POST /v1/databases/{id}/replicas

curl -X POST https://api.cloudheed.com/v1/databases/db-abc123/replicas \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read-replica-us",
    "region": "ash"
  }'

Parameters

Field	Type	Required	Description
`name`	string	Yes	Replica name
`region`	string	No	Region (default: same as primary)

Response

{
  "id": "replica-123",
  "name": "read-replica-us",
  "database_id": "db-abc123",
  "region": "ash",
  "status": "provisioning",
  "host": "replica-123.db.cloudheed.cloud",
  "port": 5432,
  "replication_lag_bytes": 0,
  "created_at": "2026-03-17T10:00:00Z"
}

List Replicas

GET /v1/databases/{id}/replicas

curl https://api.cloudheed.com/v1/databases/db-abc123/replicas \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "replicas": [
    {
      "id": "replica-123",
      "name": "read-replica-us",
      "region": "ash",
      "status": "running",
      "host": "replica-123.db.cloudheed.cloud",
      "replication_lag_bytes": 1024,
      "replication_lag_seconds": 0.5
    }
  ]
}

Get Replica Details

GET /v1/databases/{id}/replicas/{replica_id}

Delete Replica

DELETE /v1/databases/{id}/replicas/{replica_id}

curl -X DELETE https://api.cloudheed.com/v1/databases/db-abc123/replicas/replica-123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Promote Replica

Promote a replica to become a standalone primary database.

POST /v1/databases/{id}/replicas/{replica_id}/promote

curl -X POST https://api.cloudheed.com/v1/databases/db-abc123/replicas/replica-123/promote \
  -H "Authorization: Bearer YOUR_TOKEN"

⚠️

Promotion is irreversible. The replica becomes a separate database and stops receiving updates from the primary.

Replication Lag

Monitor replication lag to ensure data consistency:

Metric	Description
`replication_lag_bytes`	Bytes behind primary
`replication_lag_seconds`	Estimated time behind

Typical replication lag is under 1 second. High lag may indicate network issues or heavy write load.

Connection Pooling

Use the replica connection string for read queries:

const { Pool } = require('pg');
 
// Primary for writes
const primary = new Pool({
  connectionString: 'postgresql://cloudheed:[email protected]:5432/postgres'
});
 
// Replica for reads
const replica = new Pool({
  connectionString: 'postgresql://cloudheed:[email protected]:5432/postgres'
});
 
// Write to primary
await primary.query('INSERT INTO users (name) VALUES ($1)', ['Alice']);
 
// Read from replica
const result = await replica.query('SELECT * FROM users');

Pricing

Replicas are billed at the same rate as their primary database tier:

Primary Tier	Replica Cost
Large	€149.99/mo per replica
XL	€299.99/mo per replica
2XL	€449.99/mo per replica
4XL	€899.99/mo per replica
8XL	€1,799.99/mo per replica

Best Practices

Route reads to replicas - Use connection pooling to separate read/write traffic
Monitor replication lag - Alert on high lag values
Consider replica location - Place replicas near your users
Test failover - Periodically test promoting a replica
Account for eventual consistency - Reads from replicas may be slightly behind

Point-in-Time Recovery Metrics