This page describes how to use and promote cross-region read replicas (replicascreated in a different region from that of the primary) for regional migrationor disaster recovery.

Overview

There are two common scenarios for promoting cross-region replicas:

• Regional migration: Perform a planned migration of a database to a different region.
• Disaster recovery: Fail over a database to another region in the event that the primary's region becomes unavailable.

Both use cases involve setting up cross-region replication and then promotingthe replica. The main difference between them is whether the promotion of thereplica is planned (in the case of regional migration) or unplanned (a failoverto the replica's region is needed to continue operations because the primary hasbecome unavailable).

Note: Promoting a replica is done manually and intentionally. It is not thesame ashigh availability,where a standby instance (which is not a replica) automatically becomes theprimary in case of a failure or zonal outage.

Regional migration

You can use a cross-region replica to migrate your database to another regionwith minimal downtime. The general idea is to create a replica in anotherregion, wait until replication catches up, promote it, and then direct clientsto the newly promoted instance.

The steps involved in promotion are the same as forpromoting an in-regionreplica; follow those instructions to ensure that the newlypromoted instance has all of the transactions that were committed to theoriginal primary instance. Once you have promoted the replica and verified thatthe newly promoted instance is working, update all database clients to connectto the new instance.

Disaster recovery (DR)

Cross-region replicas can be used as part of a disaster recovery procedure. Youcan promote a cross-region replica to fail over to another region should theprimary instance's region become unavailable for an extended period of time.

For more information about disaster recovery, seeAbout disaster recovery in Cloud SQL.

Advanced disaster recovery (DR)

If you are using Cloud SQL Enterprise Plus edition, then you can designate a cross-region readreplica as a disaster recovery replica (DR replica) for advanced disaster recovery (DR).With advanced DR, you perform a replica failover to replace theprimary instance with the designated DR replica.The old primary instance becomes a replica ofthe promoted DR replica. You can only performreplica failover to the designated DR replica.You can still promote other read replicas without failover.

To return your deployment to the original state after the replica failover withzero data loss, you can perform a switchover. Since the old primary instance isa replica of the new primary instance, you can switch roles again to restore theold primary instance.

For more information, seeAdvanced disaster recovery (DR).

Verify failover criteria

Because replication is asynchronous, when a region outage occurs and afailover is attempted, some recent transactions that were committed to theprimary may be lost (not replicated to the replica). Whenever a primary instancebecomes unavailable, the following steps show (1) how to determine the amount ofdata, if any, that may have been lost in the cross-region failover and (2) howto ensure that the promoted replica reflects as many recent writes as possible.

First, check theLag Bytes values in themonitoringdashboard. When there is a region outage in the region of theprimary instance,Lag Bytes is reported for the primary instance.

Then, connect to the replica instance with a PostgreSQL client by following theinstructions in thereplication status page (see thepsql Client tab). See the instructions pertaining to thepg_catalog.pg_last_wal_receive_lsn() andpg_catalog.pg_last_wal_replay_lsn() metrics. Verify that thereplica has processed all the transactions it has received from the primary.This ensures that when promoted, the replica reflects all transactions that werereceived before the primary became unavailable.

Promote a read replica

Once you determine that the failover criteria are met, you can promote one ofthe replicas to a writeable, standalone instance. Consider the followingscenario:

• Region A (us-central1) has a High Availability primary instance (db-a-0)
• Region B (us-west1) has a High Availability cross-region replica (db-b-1) of db-a-0
• Region C (us-east1) has a cross-region replica (db-c-1) of db-a-0

You could choose to promote db-b-1 in Region B to become a standalone writableinstance.

SeePromoting a replica for detailed instructions.

Ensure the machine type is appropriate

Ensure that the machine type of the newly promoted instance is appropriate forits workload bymonitoring metrics on theinstance such as CPU and memory usage.If the newly promoted instance is smaller than its former primary instance, werecommend that you resize the promoted instance to match its former primary sothat it can handle the same amount of load.

Enable high availability for the promoted instance

For a disaster recovery configuration, we recommend that you configure thereplica that you intend to promote as a high-availability replica. Alternatively,configure the newly promoted instance as high-availability. If you choose not toconfigure the read replica with high availability, you can also configure theinstance with high availability if and when you promote it.

When promoted, read replicas are automatically configured with backups.Configuring a read replica for high availability is done the same way as for aprimary instance. For more information, seeconfiguring the instance for high availability.

Recreate additional replicas

If you promote a replica to become a primary instance, you need to recreate anyother replicas of the former primary instance. For example, consider theconfiguration referencedearlier and repeatedhere:

• Region A (us-central1) has a High Availability primary instance (db-a-0)
• Region B (us-west1) has a cross-region replica (db-b-1) of db-a-0
• Region C (us-east1) has a cross-region replica (db-c-1) of db-a-0

If the primary instance (db-a-0) becomes unavailable, you can promote the replicain region B to become the primary. To again have additional replicas inregions A and C, delete the old instances (the former primary instance in A,and the replica in C), andcreate new read replicas from the new primary instance in B.

Note: You need to use different names for the new replicas. The promotedreplica retains its original name.

The resulting configuration would be:

• Region A (us-central1) now has a cross-region replica (db-a-1)
• Region B (us-west1) now has the primary instance (db-b-1)
• Region C (us-east1) now has a new cross-region replica (db-c-2)