Nov 17, 20264 min read

Cloud SQL Read Replicas: Setup, Lag, Promotion and When to Use Them

Create a Cloud SQL for PostgreSQL read replica, watch replication lag, promote it to a standalone instance, and when a regional high-availability primary is the better tool.

Illustration for Cloud SQL Read Replicas: Setup, Lag, Promotion and When to Use Them

A Cloud SQL read replica is a copy of a Cloud SQL for PostgreSQL instance that applies changes from the primary asynchronously and can take read traffic. Teams add one when reporting, search indexing or an analytics job is crowding the writer.

A read replica is not the regional high-availability standby: the standby uses synchronous storage replication and does not serve reads, as the Cloud SQL replication overview describes. Replica replication is asynchronous, so a replica can lag, and making it writable is a promotion you start.

This guide creates a PostgreSQL replica, checks lag, and promotes it. Encore provisions Cloud SQL for PostgreSQL in your GCP account from application code, with automated daily backups, point-in-time recovery and regional (multi-AZ) availability by default, as the GCP and database availability docs describe.

Replicas at a glance

Cloud SQL read replicaRegional HA standby
ReplicationAsynchronousSynchronous storage
Serves readsYesNo
FailoverYou promote the replicaCloud SQL fails over and keeps the same IP
Created by EncoreCreate it yourself against the provisioned instanceRegional (multi-AZ) availability is the default

Create a replica

Create the replica from the primary instance. Cloud SQL creates a backup, if needed, and then creates the replica. The replica gets its own instance name and connection name. Point only read-only clients at that endpoint.

gcloud sql instances create app-replica \ --master-instance-name=app-primary \ --tier=db-custom-2-7680

Google recommends limiting a primary to 10 or fewer direct replicas. If you need more, Cloud SQL supports cascading replicas, up to four levels including the primary. You cannot restore the primary from a backup, or run point-in-time recovery on it, while its replicas still exist: promote or delete them first.

Lag, promotion and cutover

Cloud SQL publishes replication lag metrics, including cloudsql.googleapis.com/database/replication/replica_lag and database/postgresql/replication/replica_byte_lag. On the replica, pg_last_wal_receive_lsn() and pg_last_wal_replay_lsn() show whether received WAL has been applied. If lag grows through a heavy write period, pause or shed read traffic rather than serving stale rows as current.

A replica becomes writable when you promote it, and before a planned promotion you stop writes to the primary, confirm the replica's replication state is running, and wait until replay lag has caught up, or transactions still on the primary can be lost. Promotion cannot be undone: the replica stops following the old primary, and you must point writers at the new connection name yourself.

gcloud sql instances promote-replica app-replica

Automatic writer failover that keeps the same IP comes from a regional high-availability primary, and a replica adds read capacity next to it rather than replacing it.

Best fit: read-heavy traffic that can tolerate some lag, with a regional HA primary in front of writers.

How do you add a replica next to an Encore database?

Encore

Encore is a backend framework with built-in infrastructure. sqldb.NewDatabase is provisioned as Cloud SQL for PostgreSQL in your GCP account, or RDS in your AWS account, as the GCP and AWS infrastructure docs describe. encore run starts Postgres locally, and Encore provisions an IAM role for the service, or a service account on GCP.

If you need a read replica next to the Cloud SQL instance Encore provisioned, configure it in Cloud SQL or Terraform, grant the application a read-only connection string yourself, and keep read-your-writes traffic on the primary.

Best fit: Go services that want the primary declared in code, and can add and route a read replica by hand.

Create and promote a replica with gcloud

The commands above are the do-it-yourself path whether or not Encore provisioned the primary: create the replica from the primary's instance name, watch lag, and promote only after writes are stopped and replay has caught up. In Terraform, a replica is a google_sql_database_instance whose master_instance_name points at the primary.

Best fit: teams that already manage Cloud SQL in gcloud or Terraform and want the replica lifecycle in the same place as the instance.

How to choose

Use a Cloud SQL read replica when a workload can run slightly behind the writer and you are prepared to route it to a second endpoint. Use regional high availability when you need automatic writer failover. Encore provisions Cloud SQL for PostgreSQL from the database declared in your code, with regional availability by default; add a read replica in Cloud SQL if you need one.

Frequently asked questions

What is a Cloud SQL read replica?

A read replica is a second Cloud SQL instance that receives changes from a primary asynchronously and can serve read-only traffic. It is not the high-availability standby, which does not serve reads. If you need a writable instance, you promote the replica, at which point it becomes a standalone primary and stops following the old writer.

How many PostgreSQL read replicas can I create?

Google recommends limiting a primary to 10 or fewer direct read replicas. Cloud SQL also supports cascading replicas, up to four levels including the primary, as described in the Cloud SQL replication documentation. Read pools are [available only on Cloud SQL Enterprise Plus](https://docs.cloud.google.com/sql/docs/postgres/about-read-pools) instances, with their own node limits.

How do I know if a replica is falling behind?

Watch the replica lag metrics Cloud SQL publishes, including cloudsql.googleapis.com/database/replication/replica_lag and the PostgreSQL replica_byte_lag series. In PostgreSQL you can also compare pg_last_wal_receive_lsn and pg_last_wal_replay_lsn on the replica. Plan the application around lag; a read-your-writes path should use the primary.

Does Encore create Cloud SQL read replicas?

Encore provisions Cloud SQL for PostgreSQL in your GCP account, or RDS on AWS, from the database declared in your code, with automated daily backups and point-in-time recovery, as the GCP infrastructure docs describe. If you need a read replica, create it in the Cloud SQL console or with gcloud against that instance, and point read-only queries at the replica endpoint yourself.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders