Use advanced disaster recovery (DR)

MySQL | PostgreSQL | SQL Server

This page describes how to useadvanced disaster recovery (DR).Advanced DR provides two main capabilities:

Replica failover lets you fail over your primary instance to the DRreplica immediately in the event of a region failure.
Switchover lets you reverse the roles of the primary instance anda DR replica with zero data loss. You can use switchover torestore a deployment to its original deployment state after replicafailover, or you can use switchover to test DR.

Advanced DR is supported only on Cloud SQL Enterprise Plus edition instances.

Note: This page contains features related to Cloud SQL editions. Formore information about Cloud SQL editions, see Introduction to Cloud SQL editions.

Before you begin

If you plan to use the Google Cloud SDK, then you must use version 502.0.0 orlater. To check the version of theGoogle Cloud SDK, rungcloud --version. To updatethe Google Cloud SDK, rungcloud components update.

To install the Google Cloud SDK, seeInstall the gcloud CLI.

Designate a DR replica

To perform advanced DR, you must first designate a cross-region DR replica.

Primary instance requirements

The primary instance must be a Cloud SQL Enterprise Plus edition instance and have a designatedDR replica.

You must enable point-in-time recovery (PITR) on the primary instance. To enable PITR, seeUse point-in-time recovery (PITR).

If you're creatingyour Cloud SQL instance with aDNS write endpoint,then your primary instance must have the same SSL configuration as the designatedDR replica before you invoke the switchover or replica failover operation.For example, if you configure your DR replica toenforce SSL encryption,but the primary instance allows unencrypted connections, then clients won'tbe able to connect to the new primary instance after the switchoveror failover operation completes.

DR replica requirements

The designated DR read replica must meet the following requirements:

Must be a Cloud SQL Enterprise Plus edition instance

Must be the same database version as the primary instance, running PostgreSQL 12 or later

Must be in a separateregion from the primary instance
Must be a direct read replica; can't be a cascading replica

If configured with a flag that requires the replica to have a greater or equal value than the primary instance, then the flag must be configured with a value equal to the primary instance. Note that depending on the machine type (tier) and instance size of the DR replica, the default values can be different even if you have not set them explicitly. These flags are the following:
- max_connections
- max_worker_processes
- max_wal_senders
- max_prepared_transactions
- max_parallel_workers
- max_locks_per_transaction
- max_parallel_maintenance_workers
- max_parallel_workers_per_gather
Can't have thecloudsql.logical_decoding flag configured; can't have any logical slots orlogical replication configured

Must store the transaction logs used for PITR in Cloud Storage
Can't be an external replica

DR replica recommendations

This section provides recommendations for your DR replica. The followingrecommendations can help you avoid performance issues in your deployment:

Use the same disk size as the primary instance or enable auto-growth.
Use a consistent HA configuration. If you enable HA on the primaryinstance, then also enable HA on the DR replica.
Use a consistent data cache configuration. If you enable data cache onthe primary instance, then also enable data cache on the DR replica.
Configure any appropriate database flags for your DR replica before andafter any switchover or replica failover operations.
Use the same machine type (tier) and size for both the primary instanceand DR replica.

Create a replica to satisfy DR replica requirements

If the primary instance doesn't already have a cross-region read replica thatsatisfies the DR replica requirements, then create one.

Console

In the Google Cloud console, go to theCloud SQL Instances page.
Go to Cloud SQL Instances
Find the primary instance.
In theActions column, click theMore Actions menu.
SelectCreate read replica.
In theInstance ID field, enter a name for theDR replica.
In theDatabase version field, the same major version of the primary instance is selected for you.
In theChoose a region and zonal availability section of the page, do the following:
- Select a _different_ region than the region of your primary instance.
- Optional. SelectMultiple zones for the DR replica.
- Optional. Select thePrimary andSecondary zones for the DR replica.
In theCustomize your instance section of the page, you can update the settings for your DR replica. For more details about each setting, see theAbout instance settings page.
ForMachine shapes, select the same machine type as your primary instance.
ForFlags, configure any flags that are required for your database.
ClickCreate replica.

Cloud SQL creates a backup of the primary instance and creates the replica. You are returned to the instance page for the primary.

gcloud

To create a replica that meets the requirements of a DR replica, run the following command:

gcloudsqlinstancescreateREPLICA_NAME\--master-instance-name=PRIMARY_INSTANCE_NAME\--region=REPLICA_REGION_NAME\--database-version=DATABASE_VERSION\--tier=MACHINE_TYPE\--availability-type=AVAILABILITY_TYPE--edition="ENTERPRISE_PLUS"

Replace the following variables:

REPLICA_NAME: the name of the DR replica.
PRIMARY_INSTANCE_NAME: the name of the primary instance.
REPLICA_REGION_NAME: specify a region that is different than the region of the primary instance.
DATABASE_VERSION: specify the version string that matches the database major and minor version of the primary instance, for examplePOSTGRES_16.
The database major and minor versions must be the same for both the primary and DR replica.
MACHINE_TYPE: specify the same machine type as the primary instance. We recommend that the machine type matches the machine type of the primary instance.
AVAILABILITY_TYPE: if the primary instance is configured for high availability, then we recommend that you specifyREGIONAL to enable high availability.
EDITION: specifyENTERPRISE_PLUS.

Terraform

To create a DR replica, use aTerraform resource.

resource "google_sql_database_instance" "original-primary" {  name   = "postgres-original-primary-instance"  region = "us-east1"  # Specify a database version that supports Cloud SQL Enterprise Plus edition.  database_version = "POSTGRES_12"  instance_type    = "CLOUD_SQL_INSTANCE"  settings {    # Specify a tier that supports Cloud SQL Enterprise Plus edition.    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"    backup_configuration {      # You must enable automated backups and point-in-time-recovery (PITR).      enabled                        = true      point_in_time_recovery_enabled = true    }  }  # Set `deletion_protection` to true to ensure that one can't accidentally  # delete this instance by use of Terraform whereas  # `deletion_protection_enabled` flag protects this instance at the Google Cloud level.  deletion_protection = false}resource "google_sql_database_instance" "dr-replica" {  name = "postgres-dr-replica-instance"  # DR replica must be in a different region than the region of the primary instance.  region = "us-west2"  # DR replica must be the same database version as the primary instance.  database_version = "POSTGRES_12"  instance_type    = "READ_REPLICA_INSTANCE"  # Specify the primary instance as the master instance.  master_instance_name = google_sql_database_instance.original-primary.name  settings {    # DR replica must be in the same tier as your primary instance and support Enterprise Plus edition.    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"  }  # Set `deletion_protection` to true to ensure that one can't accidentally  # delete this instance by use of Terraform whereas  # `deletion_protection_enabled` flag protects this instance at the Google Cloud level.  deletion_protection = false}

REST v1

Before using any of the request data, make the following replacements:

PRIMARY_INSTANCE_NAME: the name of the primary instance.
PROJECT_ID: the ID or project number of the Google Cloud project of the primary instance and DR replica.
DATABASE_VERSION: version string that matches the database version of the primary instance, for examplePOSTGRES_16. The database version must be the same for both the primary and DR replica.
REPLICA_NAME: the name of the DR replica instance that you're creating.
REPLICA_REGION: the region of DR replica instance. The replica region must be different from the region of the primary instance.
MACHINE_TYPE: specify the same machine type as the primary instance. We recommend that you select the same machine type as the primary instance.
AVAILABILITY_TYPE: if the primary instance is configured for high availability, then we recommend that you specifyREGIONAL to enable high availability.

HTTP method and URL:

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

Request JSON body:

{  "masterInstanceName": "PRIMARY_INSTANCE_NAME",  "project": "PROJECT_ID",  "databaseVersion": "DATABASE_VERSION",  "name": "REPLICA_NAME",  "region": "REPLICA_REGION",  "settings":  {    "tier": "MACHINE_TYPE",    "availabilityType": "AVAILABILITY_TYPE",    "settingsVersion": 0,    "replicationType": "ASYNCHRONOUS",  }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by running gcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by running gcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2024-04-01T22:43:37.981Z",  "operationType": "CREATE_REPLICA",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

REST v1beta4

Before using any of the request data, make the following replacements:

PRIMARY_INSTANCE_NAME: the name of the primary instance.
PROJECT_ID: the ID or project number of the Google Cloud project of the primary instance and DR replica.
DATABASE_VERSION: version string that matches the database version of the primary instance, for examplePOSTGRES_16. The database version must be the same for both the primary and DR replica.
REPLICA_NAME: the name of the DR replica instance that you're creating.
REPLICA_REGION: the region of DR replica instance. The replica region must be different from the region of the primary instance.
MACHINE_TYPE: specify the same machine type as the primary instance. We recommend that the disk size matches the disk size of the primary instance.
AVAILABILITY_TYPE: if the primary instance is configured for high availability, then we recommend that you specifyREGIONAL to enable high availability.

HTTP method and URL:

POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

Request JSON body:

{  "masterInstanceName": "PRIMARY_INSTANCE_NAME",  "project": "PROJECT_ID",  "databaseVersion": "DATABASE_VERSION",  "name": "REPLICA_NAME",  "region": "REPLICA_REGION",  "settings":  {    "tier": "MACHINE_TYPE",    "availabilityType": "AVAILABILITY_TYPE",    "settingsVersion": 0,    "replicationType": "ASYNCHRONOUS",  }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file namedrequest.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances"

PowerShell (Windows)

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2024-04-01T22:43:37.981Z",  "operationType": "CREATE_REPLICA",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_UD/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

Designate the DR replica for the primary instance

The following procedures describe how to designate one of the cross-regionreplicas of a primary instance as a DR replica for switchover or replicafailover.

Console

To designate a DR replica for a primary instance, do the following:

In the Google Cloud console, go to theCloud SQL Instances page.
Go to Cloud SQL Instances
Find and select the primary instance. TheOverview page for the primary instance appears.
In the navigation menu, clickReplicas.
In the list of read replicas, find the cross-region read replica that you want to designate as the DR replica.
For the replica, click themore_vertActions button, and selectDesignate as DR replica.
ClickConfirm.

gcloud

To designate a DR replica for a primary instance, use the following command:

gcloudsqlinstancespatchPRIMARY_INSTANCE_NAME\--failover-dr-replica-name=REPLICA_NAME

Replace the following variables:

PRIMARY_INSTANCE_NAME: the name of the primary instance.
REPLICA_NAME: the name of the DR replica.

Terraform

To designate a DR replica for a primary instance, use aTerraform resource.

data "google_project" "default" {}resource "google_sql_database_instance" "original-primary" {  name             = "postgres-original-primary-instance"  region           = "us-east1"  database_version = "POSTGRES_12"  instance_type    = "CLOUD_SQL_INSTANCE"  replication_cluster {    # Designate the DR replica.    # The format for setting the DR replica is `project-id:dr-replica-name`.    failover_dr_replica_name = "${data.google_project.default.project_id}:postgres-dr-replica-instance"  }  settings {    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"    backup_configuration {      enabled                        = true      point_in_time_recovery_enabled = true    }  }  # Set `deletion_protection` to true to ensure that one can't accidentally  # delete this instance by use of Terraform whereas  # `deletion_protection_enabled` flag protects this instance at the Google Cloud level.  deletion_protection = false  # Optional. Add more settings.}resource "google_sql_database_instance" "dr-replica" {  name                 = "postgres-dr-replica-instance"  region               = "us-west2"  database_version     = "POSTGRES_12"  instance_type        = "READ_REPLICA_INSTANCE"  master_instance_name = google_sql_database_instance.original-primary.name  settings {    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"  }  # Set `deletion_protection` to true to ensure that one can't accidentally  # delete this instance by use of Terraform whereas  # `deletion_protection_enabled` flag protects this instance at the Google Cloud level.  deletion_protection = false  # Optional. Add more settings.}

REST v1

Before using any of the request data, make the following replacements:

PRIMARY_INSTANCE_NAME: the name of the primary instance.
REPLICA_NAME: the name of the DR replica.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME

Request JSON body:

{  "replicationCluster": {     "failoverDrReplicaName": "REPLICA_NAME"   }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME"

PowerShell (Windows)

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2024-04-01T21:30:35.667Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

REST v1beta4

Before using any of the request data, make the following replacements:

PRIMARY_INSTANCE_NAME: the name of the primary instance.
REPLICA_NAME: the name of the DR replica.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME

Request JSON body:

{  "replicationCluster": {     "failoverDrReplicaName": "REPLICA_NAME"   }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME"

PowerShell (Windows)

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2024-04-01T21:30:35.667Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

Change the DR replica designation

If the replica meets the requirements, then you can designate a differentreplica as the DR replica. The old DR replica loses the DR replicadesignation.

Console

To change the DR replica for a primary instance, do the following:

In the Google Cloud console, go to theCloud SQL Instances page.
Go to Cloud SQL Instances
Find and select the primary instance. TheOverview page for the primary instance appears.
In the navigation menu, clickReplicas.
In the list of read replicas, find the cross-region read replica that you want to designate as the new DR replica.
For the replica, click themore_vertActions button, and selectDesignate as DR replica.

gcloud

To change the DR replica, run thedesignate command again, and specify a different DR replica.

REST

To change the DR replica, make thedesignate API request again, and specify a different DR replica.

View the DR replica designation

You can check which DR replica is assigned to the primary instance by using thegcloud CLI or the Cloud SQL Admin API. You can also check whether a replica is adesignated DR replica.

To find out which DR replica is designated for a primary instance, use the following procedure.

Console

To find out which read replica is the designated DR replica for a primary instance, do the following:

In the Google Cloud console, go to theCloud SQL Instances page.
Go to Cloud SQL Instances
Find and select the primary instance. TheOverview page for the primary instance appears.
In the navigation menu, clickReplicas.
In the list of read replicas, verify thatPostgreSQL disaster recovery replica appears in theType column for the designated DR replica.

gcloud

To find out which instance is the designated DR replica of a primary instance, use the following command:

gcloudsqlinstancesdescribePRIMARY_INSTANCE_NAME

Replace the following variable:

PRIMARY_INSTANCE_NAME: the name of the primary instance

The output of this command contains the field namedfailoverDrReplica which identifies the designated DR replica.

REST v1

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance.
PRIMARY_INSTANCE_NAME: the name of the primary instance.

HTTP method and URL:

GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#instance",  "state": "RUNNABLE",  "databaseVersion": "POSTGRES_16",  "settings": {  . . .  "replicaNames": [    "my-instance-replica"  ],  "ipAddresses": [    {      "type": "PRIMARY",      "ipAddress": "192.5.4.1"    }  ],  "instanceType": "CLOUD_SQL_INSTANCE",   . . .  "connectionName": "my-project:us-east1:my-instance",  "name": "my-instance",  "region": "us-east1",  "gceZone": "us-east1-c",  "secondaryGceZone": "us-east1-b",  "databaseInstalledVersion": "POSTGRES_16",  "maintenanceVersion": "POSTGRES_16_3.R20240205.00_07","replicationCluster" {       "failoverDrReplicaName": "my-project:my-instance-replica"   },  "createTime": "2024-03-15T18:11:03.596Z",  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE"}}

REST v1beta4

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance.
PRIMARY_INSTANCE_NAME: the name of the primary instance.

HTTP method and URL:

GET https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#instance",  "state": "RUNNABLE",  "databaseVersion": "POSTGRES_16",  "settings": {  . . .  "replicaNames": [    "my-instance-replica"  ],  "ipAddresses": [    {      "type": "PRIMARY",      "ipAddress": "192.5.4.1"    }  ],  "instanceType": "CLOUD_SQL_INSTANCE",   . . .  "connectionName": "my-project:us-east1:my-instance",  "name": "my-instance",  "region": "us-east1",  "gceZone": "us-east1-c",  "secondaryGceZone": "us-east1-b",  "databaseInstalledVersion": "POSTGRES_16",  "maintenanceVersion": "POSTGRES_16_3.R20240205.00_07","replicationCluster" {       "failoverDrReplicaName": "my-project:my-instance-replica"   },  "createTime": "2024-03-15T18:11:03.596Z",  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE"}}

To check whether a replica is a DR replica, use one of the following procedures.

Console

To check whether a replica instance is a DR replica, do the following:

In the Google Cloud console, go to theCloud SQL Instances page.
Go to Cloud SQL Instances
Find the replica instance.
Verify thatPostgreSQL disaster recovery replica appears in theType column for the designated DR replica.

gcloud

To check whether a replica instance is a DR replica, run the following command:

gcloudsqlinstancesdescribeREPLICA_NAME

Replace the following variable:

REPLICA_NAME: the name of the read replica that you want to check

If the replica is a DR replica, then the output of the command contains thefielddrReplica=true.

REST v1

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance.
REPLICA_NAME: the name of the replica.

HTTP method and URL:

GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#instance",  "state": "RUNNABLE",  "databaseVersion": "POSTGRES_16",  "settings": {    "authorizedGaeApplications": [],    "tier": "db-perf-optimized-N-8",    "kind": "sql#settings",    "availabilityType": "REGIONAL",    "pricingPlan": "PER_USE",    "replicationType": "SYNCHRONOUS",    . . .    },  "masterInstanceName": "my-project:my-instance",  "ipAddresses": [    {      "type": "PRIMARY",      "ipAddress": "192.3.2.1"    }  ],  . . .  "instanceType": "READ_REPLICA_INSTANCE",  . . ."connectionName": "my-project:us-east4:my-instance-replica",  "name": "my-instance-replica",  "region": "us-east4",  "gceZone": "us-east4-b",  "secondaryGceZone": "us-east4-c",  "databaseInstalledVersion": "POSTGRES_16",  "maintenanceVersion": "POSTGRES_16_3.R20240205.00_07","replicationCluster" {       "drReplica": true  },  "createTime": "2024-03-15T18:17:44.655Z",  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE"}

REST v1beta4

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project that contains the instance.
REPLICA_NAME: the name of the replica.

HTTP method and URL:

GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#instance",  "state": "RUNNABLE",  "databaseVersion": "POSTGRES_16",  "settings": {    "authorizedGaeApplications": [],    "tier": "db-perf-optimized-N-8",    "kind": "sql#settings",    "availabilityType": "REGIONAL",    "pricingPlan": "PER_USE",    "replicationType": "SYNCHRONOUS",    . . .    },  "masterInstanceName": "my-project:my-instance",  "ipAddresses": [    {      "type": "PRIMARY",      "ipAddress": "192.3.2.1"    }  ],  . . .  "instanceType": "READ_REPLICA_INSTANCE",  . . ."connectionName": "my-project:us-east4:my-instance-replica",  "name": "my-instance-replica",  "region": "us-east4",  "gceZone": "us-east4-b",  "secondaryGceZone": "us-east4-c",  "databaseInstalledVersion": "POSTGRES_16",  "maintenanceVersion": "POSTGRES_16_3.R20240205.00_07","replicationCluster" {       "drReplica": true  },  "createTime": "2024-03-15T18:17:44.655Z",  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE"}

Remove the DR replica

You can clear the DR replica designation from a primary instance. However, ifno DR replica is assigned to a primary instance, then you can't performswitchover or replica failover.

Console

To remove a designated DR replica from a primary instance, do the following:

In the Google Cloud console, go to theCloud SQL Instances page.
Go to Cloud SQL Instances
Find and select the primary instance. TheOverview page for the primary instance appears.
In the navigation menu, clickReplicas.
In the list of read replicas, find the cross-region read replica that you want to remove.
For the replica, click themore_vertActions button, and selectRemove as DR replica.
ClickConfirm.

gcloud

To remove the DR replica designation, run the following command on the primaryinstance:

gcloudsqlinstancespatchPRIMARY_INSTANCE_NAME\--clear-failover-dr-replica-name

Replace the following variable:

PRIMARY_INSTANCE_NAME: the name of the primary instance from which you want to remove the designated DR replica

REST v1

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project of the primary instance and DR replica.
PRIMARY_INSTANCE_NAME: the name of the primary instance.
Set thefailoverDrReplicaName field to an empty string.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME

Request JSON body:

{  "replicationCluster": {     "failoverDrReplicaName": ""   }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME"

PowerShell (Windows)

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2024-04-01T21:30:35.667Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

REST v1beta4

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project of the primary instance and DR replica.
PRIMARY_INSTANCE_NAME: the name of the primary instance.
Set thefailoverDrReplicaName field to an empty string.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME

Request JSON body:

{  "replicationCluster": {     "failoverDrReplicaName": ""   }}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME"

PowerShell (Windows)

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/PRIMARY_INSTANCE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2024-04-01T21:30:35.667Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

Perform a switchover

After you've designated a DR replica, you can perform the switchover operation.However, as a best practice, avoid performing the switchover operation under thefollowing circumstances:

The primary instance is being actively used.
Admin operations are in progress, such as automated backup or theenablement or disablement of high availability (HA).

To avoid a timeout, consider performing switchover when the transaction volumeis low.

When switchover completes, the operation takes a backup of the new primaryinstance (the former DR replica) as soon as the new primary instance ispromoted.After this backup is complete, then point-in-time-recovery (PITR) is fullyenabled on the new primary instance. This backup can take between 5 and 15minutes to complete depending on the disk size. PITR coverage starts only afterthis backup has completed.For more information about the considerations of using PITR with advanced DR, seeUse PITR with advanced DR.

After the switchover operation is complete, you'll notice that the direction ofreplication is reversed.

After your old primary instance is reconfigured as a read replica,theDNS write endpoint,which previously resolved to the old primary instance, resolves to the newprimary instance.

Important:If you're not using a DNS write endpoint,then you must point your applications to use the IP address of the new primary instance.

Before you begin

Before you perform the switchover operation, do the following:

Designate a DR replica. You can only perform a switchover between the primary instance and the designated DR replica.
Verify that the primary instance and the DR replica are online.
Make sure the DR replica is running the same database version as the primary instance, PostgreSQL 12 or later.
Make sure that PITR is enabled on the primary instance. To enable PITR, seeUse point-in-time recovery (PITR).
Make sure that the primary instance and the DR replica don't have thecloudsql.logical_decoding flag configured. Neither instance can have logical slots or logical replication configured.
If you're using aDNS write endpoint, then verify that the SSL configuration for the primary instance and the DR replica are the same. For example, if the DR replica is configured toenforce SSL encryption, but the primary instance allows unencrypted connections, then clients won't be able to connect to the new primary instance after the switchover operation completes.
Take an on-demand backup of the primary instance. This backup is a precaution in case you need to recover from any unexpected failures.

Note:For Cloud SQL to update a write endpoint andpoint it to the correct instance, make sure that your replica is on the new network architecture before the switchover operation occurs. If the instance isn't created with this architecture, then you canupgrade the instance to the new network architecture.

Perform the switchover operation

Console

To perform the switchover operation, do the following:

In the Google Cloud console, go to theCloud SQL Instances page.
Go to Cloud SQL Instances
Find the designated DR replica of the primary instance.
Click the DR replica instance. TheOverview page for the DR replica appears.
Click theSwitchover button.
On thePerform switchover between the primary and DR replica page, enter the name of the primary instance in theInstance ID field.
ClickSwitchover.

gcloud

To perform the switchover operation, run the following command:

gcloudsqlinstancesswitchoverREPLICA_NAME[--db-timeout=TIMEOUT_DURATION]

Replace the following variables:

REPLICA_NAME: the name of the designated DR replica that you want the primary instance to switch roles with.
TIMEOUT_DURATION: optional. the timeout period to allow for the completion of database operations on the instance.

If you don't specify this parameter, the switchover operation includes a timeout of 10 minutes.

You can increase the value of this timeout by specifying the--db-timeout parameter. ReplaceTIMEOUT_DURATION with a time period duration of up to 24 hours, including an initial notation for the format. For example, for 30 seconds, specify30s. For 24 hours, specify24h. You can also specify fractional units of time period by using decimals up to 9 places. For example, for 30.5 minutes, specify30.5m.

If you don't have any pending operations, then you can decrease the value of this timeout.

Terraform

To begin the switchover operation, use aTerraform resource. To make the DR replica the new primary instance, use the first sample. The sample contains comments for the Terraform configuration changes you need to make to switch the primary instance and the DR replica.

## This sample provides the first part of the switchover operation and turns the DR replica# into the new primary instance.data "google_project" "default" {}resource "google_sql_database_instance" "original-primary" {  name             = "postgres-original-primary-instance"  region           = "us-east1"  database_version = "POSTGRES_12"  instance_type    = "CLOUD_SQL_INSTANCE"  replication_cluster {    failover_dr_replica_name = "${data.google_project.default.project_id}:postgres-dr-replica-instance"  }  settings {    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"    backup_configuration {      enabled                        = true      point_in_time_recovery_enabled = true    }  }  # Set `deletion_protection` to true to ensure that one can't accidentally  # delete this instance by use of Terraform whereas  # `deletion_protection_enabled` flag protects this instance at the Google Cloud level.  deletion_protection = false  # Optional. Add more settings.}resource "google_sql_database_instance" "dr-replica" {  name             = "postgres-dr-replica-instance"  region           = "us-west2"  database_version = "POSTGRES_12"  # Change the instance type from "READ_REPLICA_INSTANCE" to "CLOUD_SQL_INSTANCE".  instance_type = "CLOUD_SQL_INSTANCE"  # Remove or comment out the master_instance_name from the DR replica.  # master_instance_name = google_sql_database_instance.original-primary.name  # Add the original primary instance to a list of replicas for the new primary.  replica_names = [google_sql_database_instance.original-primary.name]  # Designate the original primary instance as the DR replica of the new primary instance.  # The format for setting the DR replica is `project-id:dr-replica-name`.  replication_cluster {    failover_dr_replica_name = "${data.google_project.default.project_id}:${google_sql_database_instance.original-primary.name}"  }  settings {    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"    backup_configuration {      # Add a backup configuration section to enable automated backups and point-in-time-recovery (PITR) for the new primary instance.      enabled                        = true      point_in_time_recovery_enabled = true    }  }  # Set `deletion_protection` to true to ensure that one can't accidentally  # delete this instance by use of Terraform whereas  # `deletion_protection_enabled` flag protects this instance at the Google Cloud level.  deletion_protection = false  # Optional. Add more settings.}

After you make your changes, update the primary and DR replica by runningterraform plan. Verify that the output includesPlan: 0 to add, 1 to change, 0 to destroy. To perform the switchover, runterraform apply.

At this point, the original primary is a replica of the new primary instance. However, that change isn't reflected in your Terraform state automatically. To make the original primary instance a replica of the new primary instance in your Terraform state, use the second sample. The second sample provides comments that describe the changes you need to make after running the first sample.

# This sample provides the second part of the switchover operation and makes the original primary instance# a replica of the new primary instance. After you run `terraform apply` for this sample, you'll see# the following message:## "No changes. Your infrastructure matches the configuration.## Terraform has compared your real infrastructure against your configuration and found no differences,# so no changes are needed.## Apply complete! Resources: 0 added, 0 changed, 0 destroyed."data "google_project" "default" {}resource "google_sql_database_instance" "original-primary" {  name             = "postgres-original-primary-instance"  region           = "us-east1"  database_version = "POSTGRES_12"  # Change instance type for the original primary from "CLOUD_SQL_INSTANCE" to "READ_REPLICA_INSTANCE".  instance_type = "READ_REPLICA_INSTANCE"  # Set master_instance_name to the the new primary instance, the old DR replica.  master_instance_name = "postgres-dr-replica-instance"  # replica_names = [] # If you previously defined a replica_names field in your template, then delete the DR replica  # (new primary) from the list of replicas.  Don't delete the entire replica_names field.  # Instead set the field to an empty string. For example, replica_names = [""].  replication_cluster {    # This instance no longer requires a designated DR replica since it's a replica.    # Remove the DR replica designation by setting the field to an empty string.    failover_dr_replica_name = ""  }  settings {    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"    backup_configuration {      # Disable automated backups and PITR because this instance is now a replica.      enabled                        = false      point_in_time_recovery_enabled = false    }  }  # Set `deletion_protection` to true to ensure that one can't accidentally  # delete this instance by use of Terraform whereas  # `deletion_protection_enabled` flag protects this instance at the Google Cloud level.  deletion_protection = false  # Optional. Add more settings.}resource "google_sql_database_instance" "dr-replica" {  name             = "postgres-dr-replica-instance"  region           = "us-west2"  database_version = "POSTGRES_12"  instance_type    = "CLOUD_SQL_INSTANCE"  replica_names    = [google_sql_database_instance.original-primary.name]  replication_cluster {    failover_dr_replica_name = "${data.google_project.default.project_id}:${google_sql_database_instance.original-primary.name}"  }  settings {    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"    backup_configuration {      enabled                        = true      point_in_time_recovery_enabled = true    }  }  # Set `deletion_protection` to true to ensure that one can't accidentally  # delete this instance by use of Terraform whereas  # `deletion_protection_enabled` flag protects this instance at the Google Cloud level.  deletion_protection = false  # Optional. Add more settings.}

If your Terraform state is updated successfully, then when you runterraform plan against the second sample, a message similar to the following appears:

No changes. Your infrastructure matches the configuration.

If you runterraform apply, then you receive a message similar to the following:

Resources: 0 added, 0 changed, 0 destroyed.

REST v1

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project of the primary instance and the DR replica.
REPLICA_NAME: the name of the DR replica.

HTTP method and URL:

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/switchover

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/switchover"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/switchover" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2024-04-01T22:43:37.981Z",  "operationType": "SWITCHOVER",  "name": "OPERATION_ID",  "targetId": "REPLICA_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

REST v1beta4

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project of the primary instance and the DR replica.
REPLICA_NAME: the name of the DR replica.

HTTP method and URL:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME/switchover

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME/switchover"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME/switchover" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2024-04-01T22:43:37.981Z",  "operationType": "SWITCHOVER",  "name": "OPERATION_ID",  "targetId": "REPLICA_ID",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

Perform DR by invoking a replica failover

In the event of region failure or a disaster, you can perform DR byinvoking a replica failover operation to your designated DR replica. To performa replica failover, you promote the designated DR replica. In contrast with switchover, the promotion of the DR replica isimmediate.

Since the DR replica assumes the role of the primary instance immediately,it's possible that the replica doesn't have all of the data from theold primary instance due to replication lag. For this reason, a replica failovercan incur data loss.

As part of the promotion process, replica failover takes a backup of the newprimary instance (the former DR replica) right after the DR replica becomes thenew primary instance. After this backup is complete, point-in-time-recovery(PITR) is fully enabled on the new primary instance. This backup can takebetween 5 and 15 minutes to complete depending on the disk size of the new (andold) primary instance. During this backup period, PITR isn't available.

When the old primary instance comes back online, the replica failover processtakes a backup. After this backup is taken, the old primary instance isrecreated as a read replica of the new primary instance.

For more information about the considerations of using PITR with advanced DR,seeUse PITR with advanced DR.

After you invoke the replica failoveroperation, theDNS write endpoint,which previously resolved to the old primary instance,resolves to the new primary instance.

Important:If you're not using a DNS write endpoint,then you must point your applications to use the IP address of the new primary instance.

Before you begin

Before you can perform a replica failover, do the following:

If you haven't done so already, then designate a DR replica. You can only perform a replica failover between the primary instance and the designated DR replica.
Make sure the DR replica is online and healthy.
Make sure the DR replica is running the same database version as the primary instance, PostgreSQL 12 or later.
Make sure that PITR is enabled on the primary instance. To enable PITR, seeUse point-in-time recovery (PITR).
Make sure that the primary instance and the DR replica don't have thecloudsql.logical_decoding flag configured. Neither instance can have logical slots or logical replication configured. If you invoke replica failover and the original primary has logical decoding enabled, then when the original primary becomes a read replica, any logical slots configured on the original primary instance are lost.

Note:For Cloud SQL to update a write endpoint andpoint it to the correct instance, make sure that your replica is on the new network architecture before the replica failover operation occurs. If the instance isn't created with this architecture, then you canupgrade the instance to the new network architecture.

Perform the replica failover operation

Console

To perform the replica failover operation, do the following:

In the Google Cloud console, go to theCloud SQL Instances page.
Go to Cloud SQL Instances
Click the DR replica instance. TheOverview page for the DR replica appears.
Click theReplica Failover button.
On thePerform replica failover between the primary and DR replica page, enter the name of the primary instance in theInstance ID field to confirm that you want to proceed with the operation.
To start the replica failover, clickReplica Failover.

gcloud

To invoke a replica failover to the DR replica, use the following command:

gcloudsqlinstancespromote-replica\REPLICA_NAME--failover

Replace the following variable:

REPLICA_NAME: the name of the DR replica

REST v1

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project of the primary instance and DR replica.
REPLICA_NAME: the name of the DR replica.
ENABLE_REPLICA_FAILOVER: set totrue to use replica failover. If you set to false, then the API uses the regularpromoteReplica method without replica failover.

HTTP method and URL:

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/promoteReplica?failover=ENABLE_REPLICA_FAILOVER

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/promoteReplica?failover=ENABLE_REPLICA_FAILOVER"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/promoteReplica?failover=ENABLE_REPLICA_FAILOVER" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "PROMOTE_REPLICA",  "name": "OPERATION_ID",  "targetId": "REPLICA_NAME",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

REST v1beta4

Before using any of the request data, make the following replacements:

PROJECT_ID: the ID or project number of the Google Cloud project of the primary instance and DR replica.
REPLICA_NAME: the name of the DR replica.
ENABLE_REPLICA_FAILOVER: set totrue to use replica failover. If you set to false, then the API uses the regularpromoteReplica method without replica failover.

HTTP method and URL:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME/promoteReplica?failover=ENABLE_REPLICA_FAILOVER

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME/promoteReplica?failover=ENABLE_REPLICA_FAILOVER"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME/promoteReplica?failover=ENABLE_REPLICA_FAILOVER" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/REPLICA_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2024-04-01T22:43:37.981Z",  "operationType": "PROMOTE_REPLICA",  "name": "OPERATION_ID",  "targetId": "REPLICA_NAME",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

Check the status of a replica failover

Replica failover occurs in two phases.The first phase is the promotion of the DR replica.The second phase is the recreation ofthe old primary instance as a read replica.

To check the status of replica failover, check the status of eachphase.

Check the status of the first phase.
Console
To check if the DR replica has been promoted to a standalone instance, do the following:
1. In the Google Cloud console, go to theCloud SQL Instances page.
  Go to Cloud SQL Instances
2. Find the name of the DR replica that you promoted.
3. Verify thatPostgreSQLVERSION appears in theType column for the new primary instance.
gcloud
You can check the status by running the following command:
```
gcloudsqlinstancesdescribeDR_REPLICA_NAME
```
Replace the following variable:
- DR_REPLICA_NAME: the name of the promoted DR replica
In the output, check that the following field appears and thereplica has become a standalone Cloud SQL primary instance:
```
instanceType: CLOUD_SQL_INSTANCE
```
To verify the completion of the second phase, check theoperations log on the instance for the messageRECONFIGURE_OLD_PRIMARY.
The appearance of this message depends on when the oldprimary instance returns online, which can take minutes ordays in the event of a disaster.
For more information on how to check the operations logs on an instance, seeView instance logs.

Use PITR with advanced DR

With both switchover and replica failover, as soon as the DR replica ispromoted to a primary instance, the following changes occur to support backupand PITR:

Backup configuration, including any automated backup scheduling, iscopied from the old primary instance to the new primary instance.

A new backup is taken to support PITR on the new primary instance.
The transaction log retention policy is copied from the old primaryinstance to the new primary instance.

For both the backup configuration and transaction log retention policies, werecommend that you verify that the settings inherited from the old primaryinstance are correct for the new primary instance.

Start of PITR coverage

At the end of the switchover operation, Cloud SQL schedulesautomated backups and takes the first backup of the new primary instance.If you want PITR coverage to begin sooner than later,then we recommend that you verify that the first backup issuccessful. The newly promoted primary instance has PITR coverageonly afterthe first automated backup has completed successfully.

For more information about how to view the backups that are available for aninstance, seeView a list of backups.

PITR coverage for instances during switchover and replica failover

When an instance participates in a switchover or a replica failover operation,the instance spends time as a read replica. PITR and restoring a backup aresupported during the time period that the instance spends as a read replica andas a primary instance.

You can perform PITR to a time before the switchover when the instance was aprimary instance.For both switchover and replica failover operations, Cloud SQL initiatesa best-effort backup for the new primary instanceas soon as the new primary instance is promoted. PITR is enabled on thepromoted instance only after this backup is completed.This backup can take 5 to 15 minutes to complete depending on the disk size.

Split-brain during replica failover

It's possible that split-brain occurs when the primary instance continues toaccept writes while a replica is promoted using replica failover. After thereplica is promoted, when the old primary instance is available again, it isrebuilt as a replica of the promoted instance and a final backup is made. Thisbackup can be used to recover any split-brain data that was not written to thepromoted replica.

Note: Split-brain can't happen for switchover operations.

Deletion of backups and transaction logs on replicas

If a primary instance that was enabled with PITR and backups becomes a readreplica, then the last backup and PITR retention policy from its time as aprimary instance is preserved and applied during its time as a replica. Eventhough the new primary instance is not taking backups, the old backups andtransaction logs used for PITR are deleted on the read replica according to thelast configured policy.

For example, if the instance is configured to have daily automated backups andkeep 7 backups with 7 days of PITR logs, then when this instance becomes a readreplica, anything older than 7 days is deleted once a day.

If you need to delete backups sooner, then you can remove backups manually. Formore information, see Delete a backup.

Note: You can't modify backup configuration settings while the instance is areplica.

Recommendations for VPC Service Controls and advanced DR

If you use VPC Service Controls, then make sure that your service perimeters allownecessary communications for all recovery operations such as point-in-timerecovery (PITR) operations, especially when you use CMEK with keys in adifferent project.

Advanced DR operations, like switchover and replica failover, can enable orreconfigure features like PITR, which can be blocked by VPC Service Controls ifthe service perimeters aren't configured correctly for CMEK and cross-projectkey access.

Keep KMS key project in same perimeter as instance: as a best practice, include the project containing the KMS key in the same VPC Service Controls perimeter as your Cloud SQL instances.

Use a perimeter bridge: as a secondary (less recommended) option, you can use a perimeter bridge to connect projects in different perimeters.
Test: use VPC Service Controls dry run mode to test your DR procedures (like switchover) and identify potential VPC Service Controls violations without enforcement.

For more information, seeConfigureVPC Service Controls.

Limitations

You can't designate a Cloud SQL Enterprise Plus edition read replicainstance as DR replica if the primary instance stores its transaction logsfor point-in-time recovery (PITR) on disk. To check where an instancestores its logs for PITR, seeCheck the storage location of transaction logs used for PITR.
You can't designate an external replica as a DR replica.
Terraform isn't supported for replica failover operations.

Troubleshoot

Issue	Troubleshooting
Switchover operation has failed.	Check the volume of transactions on the database. If the transaction volume is high, then the operationmight timeout. Consider retrying the operation when the transaction load islower.
Switchover operation has failed and the primary instance is stuck inread-only mode.	Perform a database restart to bring the primary instance back towrite mode.
Switchover operation has completed, but the Google Cloud console doesn't show thenew reversed roles for the instances.	Refresh your browser to show the updated topology.
Replica failover operation has failed.	If failover to the DR replica has failed, then promote to aregular (non-DR) read replica instead.

What's next

View all theGoogle Cloud services available in locations worldwide.
Read aboutdatabase observability
Monitor Cloud SQL instances

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.

Movatterモバイル変換

Use advanced disaster recovery (DR) Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Designate a DR replica

Primary instance requirements

DR replica requirements

DR replica recommendations

Create a replica to satisfy DR replica requirements

Console

gcloud

Terraform

REST v1

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

REST v1beta4

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

Designate the DR replica for the primary instance

Console

gcloud

Terraform

REST v1

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

REST v1beta4

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

Change the DR replica designation

Console

gcloud

REST

View the DR replica designation

Console

gcloud

REST v1

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

REST v1beta4

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

Console

gcloud

REST v1

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

REST v1beta4

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

Remove the DR replica

Console

gcloud

REST v1

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

REST v1beta4

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

Perform a switchover

Before you begin

Perform the switchover operation

Console

gcloud

Terraform

REST v1

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Response

REST v1beta4

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Use advanced disaster recovery (DR)