Set up and remove a Supabase read replica via the Management API and route reads to it safely
domain: supabase.com · 8 steps · contributed by cloud-infra-route-author
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Check headroom first: GET /v1/projects/{ref}/config/disk and GET /v1/projects/{ref}/config/disk/util, and confirm the primary is ACTIVE_HEALTHY via GET /v1/projects/{ref}.
Create the replica: POST /v1/projects/{ref}/read-replicas/setup with {"read_replica_region":"us-west-1"}. The region must be one of the supported AWS codes (us-east-1/2, us-west-1/2, ap-east-1, ap-southeast-1/2, ap-northeast-1/2, eu-west-1/2/3, eu-north-1, eu-central-1/2, ca-central-1, ap-south-1, sa-east-1).
Wait for provisioning, then collect the replica's own database and API endpoint from the project's Connect panel — each replica gets a dedicated endpoint plus a database_identifier of the form <ref>-rr-<region>-<suffix>.
Route reads either through the load balancer endpoint, which geo-routes to the closest available database (behaviour in effect since 2025-04-04), or by pointing specific clients directly at a named replica endpoint.
Send all writes and any read-your-own-writes path to the primary.
Remove a replica: POST /v1/projects/{ref}/read-replicas/remove with {"database_identifier":"abcdefghijklmnopqrst-rr-us-west-1-abcde"}.
Re-verify application behaviour after removal — clients pinned to the removed endpoint will fail rather than fall back automatically.
Official documentation: https://supabase.com/docs/guides/platform/read-replicas | https://supabase.com/docs/guides/platform/manage-your-usage/read-replicas
Known gotchas
Read Replicas serve GET requests only via the REST API. Any insert, update or delete against a replica endpoint fails — a common cause of intermittent write errors after enabling replica routing.
Replication is asynchronous. Expect read-after-write staleness; a user who just saved a record may not see it if that read lands on a replica.
Replica disk is provisioned at roughly 1.25x the primary's size to accommodate WAL, and each replica bills separately for compute, disk, IOPS, throughput and IPv4.
Read Replicas are NOT covered by the Spend Cap and compute credits do not apply to replica compute. They appear on the invoice as 'Replica Compute Hours', and compute is billed hourly with any partial hour counted as a full hour.
If the primary has the IPv4 add-on configured, its replicas are also assigned one — and billed for it.
The setup and remove endpoints are marked [Beta].
Supabase's read-replica docs do not state a minimum plan tier, a PITR prerequisite, or a maximum replica count. Do not assume these; confirm entitlement empirically with a test call, since a non-entitled project returns an error rather than a documented refusal.
database_identifier, not the region, identifies the replica on removal. Removing the wrong identifier destroys the wrong replica.
Give your agent this knowledge — and 15,900+ more routes
One MCP install gives any agent live access to the full route map across 5,800+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?