Create and manage read pools

MySQL  |  PostgreSQL  |  SQL Server

This page describes how to create and manageread poolsfor your large read workloads.

Before you begin

  1. Read pools contain copies of a primary instance. If you haven't done so already, create aCloud SQL Enterprise Plus edition primary instance. While read pools support public IP connectivity, for the purpose of this guide, create a primary instance with private IP (PSA) connectivity. For more information about primary instances and replication, seeAbout replication in Cloud SQL.
  2. After the primary instance is created, choose a password for the root user and run the following command to set the password on the primary instance. Save this password to use later when connecting to the read pool.
    3. gcloud--project=PROJECT\sqlusersset-passwordroot--host=%\--instance=PRIMARY_INSTANCE_NAME--prompt-for-password
    Make sure you're usinggcloud v532.0.0 or later.

    Make the following replacements:

    • PROJECT: the name of the project where you want the primary instance and read pool to reside.
    • PRIMARY_INSTANCE_NAME: the name of the primary instance.

Create a read pool

gcloud

For information about installing and getting started with the gcloud CLI, seeInstall the gcloud CLI. For information about starting Cloud Shell, seeUse Cloud Shell.

Use the followinggcloud sql instances create command to create a read pool with multiple read pool nodes:

gcloudsqlinstancescreateREAD_POOL_NAME\--tier=TIER--edition=ENTERPRISE_PLUS\--instance-type=READ_POOL_INSTANCE--node-count=NODE_COUNT\--master-instance-name=PRIMARY_INSTANCE_NAME

Make the following replacements:

  • READ_POOL_NAME: the name you want to use for the read pool.
  • TIER: the machine type you want to use for each read pool node in the read pool, such asdb-perf-optimized-N-4.
  • NODE_COUNT: the number of read pool nodes you want in the read pool. Choose any number from1 to20.
  • PRIMARY_INSTANCE_NAME: the name of the primary instance associated with the read pool, such asmy-primary-instance.

Terraform

To create a read pool, use aTerraform resource. Then, set theinstance_type attribute to"READ_POOL_INSTANCE" and thenode_count attribute to the number of nodes you want to use.

The following example includes resources for the primary instance and the read pool.

resource "google_sql_database_instance" "primary" {  name             = "postgres-primary"  database_version = "POSTGRES_17"  region           = "europe-west4"  instance_type = "CLOUD_SQL_INSTANCE"  settings {    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"    backup_configuration {      enabled = true    }    ip_configuration {      ipv4_enabled = true    }  }}resource "google_sql_database_instance" "replica" {  name             = "postgres-replica"  database_version = "POSTGRES_17"  region           = "europe-west4"  master_instance_name = google_sql_database_instance.primary.name  instance_type        = "READ_POOL_INSTANCE"  node_count           = 2  settings {    tier    = "db-perf-optimized-N-2"    edition = "ENTERPRISE_PLUS"    ip_configuration {      ipv4_enabled = true    }  }}

Apply the changes

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

  1. LaunchCloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (alsocalled aroot module).

  1. InCloud Shell, create a directory and a new file within that directory. The filename must have the.tf extension—for examplemain.tf. In this tutorial, the file is referred to asmain.tf.
    mkdirDIRECTORY && cdDIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly createdmain.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory.
    terraform init

    Optionally, to use the latest Google provider version, include the-upgrade option:

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

Delete the changes

To delete your changes, do the following:

  1. To disable deletion protection, in your Terraform configuration file set thedeletion_protection argument tofalse.
    deletion_protection =  "false"
  2. Apply the updated Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

  1. Remove resources previously applied with your Terraform configuration by running the following command and enteringyes at the prompt:

    terraform destroy

REST v1

Use theinsert method of the instances resource to create a read pool with multiple read pool nodes. ThedatabaseVersion property must be the same as the primary.

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

  • PROJECT: the name of the project where you want the primary instance and read pool to reside.
  • REGION: the region for the read pool, such asus-east1. The region must be the same as the primary instance.
  • TIER: the machine type you want to use for each read pool node in the read pool, such asdb-perf-optimized-N-4.
  • PRIMARY_INSTANCE_NAME: the name of the primary instance.
  • READ_POOL_NAME: the name you want to use for the read pool, such asmy-read-pool.
  • DATABASE_VERSION: the database version you want to use. For example,POSTGRES_16.
  • NODE_COUNT: the number of read pool nodes you want in the read pool. Choose any number from1 to20.
  • FULL_NETWORK_NAME: the full network path where you want the read pool to reside, such asprojects/vpc-host-project/global/networks/my-network-name.

HTTP method and URL:

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

Request JSON body:

{  "name": "READ_POOL_NAME",  "masterInstanceName": "PRIMARY_INSTANCE_NAME",  "project": "PROJECT",  "databaseVersion": "DATABASE_VERSION",  "region": "REGION",  "instanceType": "READ_POOL_INSTANCE",  "nodeCount":NODE_COUNT,  "settings": {    "tier": "TIER",    "edition": "ENTERPRISE_PLUS",    "ipConfiguration": {      "ipv4Enabled": false,      "privateNetwork": "FULL_NETWORK_NAME"    }  }}

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 runninggcloud 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/instances"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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/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/instances/READ_POOL_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "CREATE_READ_POOL",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

REST v1beta4

Use theinsert method of the instances resource to create a read pool with multiple read pool nodes. ThedatabaseVersion property must be the same as the primary.

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

  • PROJECT: the name of the project where you want the primary instance and read pool to reside.
  • REGION: the region for the read pool, such asus-east1. The region must be the same as the primary instance.
  • TIER: the machine type you want to use for each read pool node in the read pool, such asdb-perf-optimized-N-4.
  • PRIMARY_INSTANCE_NAME: the name of the primary instance.
  • READ_POOL_NAME: the name you want to use for the read pool, such asmy-read-pool.
  • DATABASE_VERSION: the database version you want to use. For example,POSTGRES_16.
  • NODE_COUNT: the number of read pool nodes you want in the read pool. Choose any number from1 to20.
  • FULL_NETWORK_NAME: the full network path where you want the read pool to reside, such asprojects/vpc-host-project/global/networks/my-network-name.

HTTP method and URL:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances

Request JSON body:

{  "name": "READ_POOL_NAME",  "masterInstanceName": "PRIMARY_INSTANCE_NAME",  "project": "PROJECT",  "databaseVersion": "DATABASE_VERSION",  "region": "REGION",  "instanceType": "READ_POOL_INSTANCE",  "nodeCount":NODE_COUNT,  "settings": {    "tier": "TIER",    "edition": "ENTERPRISE_PLUS",    "ipConfiguration": {      "ipv4Enabled": false,      "privateNetwork": "FULL_NETWORK_NAME"    }  }}

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 runninggcloud 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/sql/v1beta4/projects/PROJECT/instances"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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/sql/v1beta4/projects/PROJECT/instances" | 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/instances/READ_POOL_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "CREATE_READ_POOL",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

Convert a read replica to a read pool

You can convert an existing Cloud SQL Enterprise Plus edition read replica into a read pool byspecifying the number of nodes in the pool. Duringthis conversion process, the replica IP will become the read pool IP(the read endpoint), so existing clients can connect to the poolwithout reconfiguration.

The newly created read pool nodes will have the samemachine type and configuration as the original read replica. Changingthis machine type or configuration requires a separate operation. Thisoperation is only supported for zonal read replicas. Toconvert a highlyavailable (HA) read replica to a read pool, you must first convert it to a zonal read replica.

For more information, seeEdit read pool configuration.

gcloud

For information about installing and getting started with the gcloud CLI, seeInstall the gcloud CLI. For information about starting Cloud Shell, seeUse Cloud Shell.

Use the followinggcloud sql instances patch command to convert a read replica for use with a read pool:

gcloudsqlinstancespatchREAD_REPLICA_NAME\--instance-type=READ_POOL_INSTANCE--node-count=NODE_COUNT

Make the following replacements:

  • READ_REPLICA_NAME: the name of the read replica you want to convert.
  • NODE_COUNT: the number of read pool nodes you want in the read pool. Choose any number from1 to20.

Terraform

To convert a read replica to a read pool, use aTerraform resource. The manifest looks similar to the one you used inCreate a read replica. Then, complete the following steps:

  • Change theinstance_type attribute from"READ_REPLICA_INSTANCE" to"READ_POOL_INSTANCE" and thenode_count attribute to the number of nodes you want to use.
  • If you previously set it, clear thesettings.availability_type attribute.

REST v1

Use thepatch method of the instances resource to convert a read replica to a read pool.

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

  • READ_REPLICA_NAME: the name of the read replica you wish to convert, such asmy-read-replica.
  • NODE_COUNT: the number of read pool nodes you want in the read pool. Choose any number from1 to20.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_REPLICA_NAME

Request JSON body:

{  "instanceType": "READ_POOL_INSTANCE",  "nodeCount":NODE_COUNT}

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 runninggcloud 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 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/instances/READ_REPLICA_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_REPLICA_NAME" | 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/instances/READ_REPLICA_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "READ_REPLICA_NAME",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

REST v1beta4

Use thepatch method of the instances resource to convert a read replica to a read pool.

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

  • READ_REPLICA_NAME: the name of the read replica you wish to convert, such asmy-read-replica.
  • NODE_COUNT: the number of read pool nodes you want in the read pool. Choose any number from1 to20.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_REPLICA_NAME

Request JSON body:

{  "instanceType": "READ_POOL_INSTANCE",  "nodeCount":NODE_COUNT}

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 runninggcloud 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 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/instances/READ_REPLICA_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_REPLICA_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/instances/READ_REPLICA_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "READ_REPLICA_NAME",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

Convert a read pool to a read replica

gcloud

For information about installing and getting started with the gcloud CLI, seeInstall the gcloud CLI. For information about starting Cloud Shell, seeUse Cloud Shell.

Use the followinggcloud sql instances patch command to convert a read replica for use with a read pool:

gcloudsqlinstancespatchREAD_POOL_NAME\--instance-type=READ_REPLICA_INSTANCE--availability-type=ZONAL

Make the following replacements:

  • READ_POOL_NAME: the name of the read pool you want to convert.

Terraform

To convert a read pool to a read replica, use aTerraform resource. The manifest looks similar to the one you used inCreate a read pool. Then, change theinstance_type attribute from"READ_POOL_INSTANCE" to"READ_REPLICA_INSTANCE", clear thenode_count attribute, and set thesettings.availability_type attribute toZONAL.

REST v1

Use thepatch method of the instances resource to convert a read pool to a read replica.

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

  • READ_POOL_NAME: the name of the read pool, such asmy-read-pool.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_POOL_NAME

Request JSON body:

{  "instanceType": "READ_REPLICA_INSTANCE",  "settings": {    "availabilityType": "ZONAL"  }}

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 runninggcloud 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 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/instances/READ_POOL_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_POOL_NAME" | 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/instances/READ_POOL_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "READ_POOL_NAME",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

REST v1beta4

Use thepatch method of the instances resource to convert a read pool to a read replica.

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

  • READ_POOL_NAME: the name of the read pool, such asmy-read-pool.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_POOL_NAME

Request JSON body:

{  "instanceType": "READ_REPLICA_INSTANCE",  "settings": {    "availabilityType": "ZONAL"  }}

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 runninggcloud 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 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/instances/READ_POOL_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_POOL_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/instances/READ_POOL_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "READ_POOL_NAME",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

View read pool information

gcloud

For information about installing and getting started with the gcloud CLI, seeInstall the gcloud CLI. For information about starting Cloud Shell, seeUse Cloud Shell.

Use the followinggcloud sql instances describe command to describe the read pool:

gcloudsqlinstancesdescribeREAD_POOL_NAME

Make the following replacements:

  • READ_POOL_NAME: the name of the read pool you want to describe.

An example response with IP address and node information, might look similar to the following:

...connectionName:my-project:us-central1:read-poolipAddresses:-ipAddress:10.3.0.108type:PRIVATEnodeCount:2nodes:-dnsName:c5bdacb09ffc.j10o8yqc7pve.us-central1.sql.goog.gceZone:us-central1-fipAddresses:-ipAddress:10.3.0.112type:PRIVATEname:read-pool-node-01state:RUNNABLE-dnsName:8f77c454d6b2.j10o8yqc7pve.us-central1.sql.goog.gceZone:us-central1-cipAddresses:-ipAddress:10.3.0.113type:PRIVATEname:read-pool-node-02state:RUNNABLE

REST v1

Use theget method to view read pool details.

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

  • PROJECT: the name of the project where the read pool resides.
  • READ_POOL_NAME: the name of the read pool, such asmy-read-pool.

HTTP method and URL:

GET https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_POOL_NAME

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 runninggcloud 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.

Execute the following command:

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

PowerShell (Windows)

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

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/instances/READ_POOL_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  [...],  "connectionName": "my-project:us-central1:read-pool",  "ipAddresses": [    {      "type": "PRIVATE",      "ipAddress": "10.3.0.108"    }  ],  "nodeCount": 2,  "nodes": [    {      "ipAddresses": [        {          "type": "PRIVATE",          "ipAddress": "10.3.0.112"        }      ],                                                                                                                       "name": "read-pool-node-01",      "gceZone": "us-central1-f",      "dnsName": "c5bdacb09ffc.j10o8yqc7pve.us-central1.sql.goog.",      "state": "RUNNABLE"    },    {      "ipAddresses": [        {          "type": "PRIVATE",          "ipAddress": "10.3.0.113"        }      ],      "name": "read-pool-node-02",      "gceZone": "us-central1-c",      "dnsName": "8f77c454d6b2.j10o8yqc7pve.us-central1.sql.goog.",      "state": "RUNNABLE"    }  ]}

REST v1beta4

Use theget method to view read pool details.

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

  • PROJECT: the name of the project where the read pool resides.
  • READ_POOL_NAME: the name of the read pool, such asmy-read-pool.

HTTP method and URL:

GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_POOL_NAME

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 runninggcloud 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.

Execute the following command:

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

PowerShell (Windows)

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

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/instances/READ_POOL_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{  [...],  "connectionName": "my-project:us-central1:read-pool",  "ipAddresses": [    {      "type": "PRIVATE",      "ipAddress": "10.3.0.108"    }  ],  "nodeCount": 2,  "nodes": [    {      "ipAddresses": [        {          "type": "PRIVATE",          "ipAddress": "10.3.0.112"        }      ],                                                                                                                       "name": "read-pool-node-01",      "gceZone": "us-central1-f",      "dnsName": "c5bdacb09ffc.j10o8yqc7pve.us-central1.sql.goog.",      "state": "RUNNABLE"    },    {      "ipAddresses": [        {          "type": "PRIVATE",          "ipAddress": "10.3.0.113"        }      ],      "name": "read-pool-node-02",      "gceZone": "us-central1-c",      "dnsName": "8f77c454d6b2.j10o8yqc7pve.us-central1.sql.goog.",      "state": "RUNNABLE"    }  ]}

Add or remove read pool nodes

The following steps scale a read pool in or out by modifying the number of readpool nodes in the read pool. Some operation limitations apply. For moreinformation, seeRead pool limitations.

gcloud

For information about installing and getting started with the gcloud CLI, seeInstall the gcloud CLI. For information about starting Cloud Shell, seeUse Cloud Shell.

Use the followinggcloud sql instances patch command to scale the read pool:

gcloudsqlinstancespatchREAD_POOL_NAME\--node-count=NODE_COUNT

Make the following replacements:

  • READ_POOL_NAME: the name of the read pool.
  • NODE_COUNT: the number of read pool nodes you want in the read pool. Choose any number from1 to20.

Terraform

To change the number of read pool nodes, update an existingTerraform resource. The manifest looks similar to the one you used inCreate a read pool. Then, change thenode_count attribute to the number of nodes you want to use.

REST v1

Use thepatch method to scale a read pool in or out by modifying the number of read pool nodes in the read pool.

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

  • PROJECT: the name of the project where the read pool resides.
  • NODE_COUNT: the number of read pool nodes you want in the read pool. Choose any number from1 to20.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_POOL_NAME

Request JSON body:

{  "nodeCount":NODE_COUNT}

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 runninggcloud 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 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/instances/READ_POOL_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_POOL_NAME" | 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/instances/READ_POOL_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "READ_POOL_NAME",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

REST v1beta4

Use thepatch method to scale a read pool in or out by modifying the number of read pool nodes in the read pool.

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

  • PROJECT: the name of the project where the read pool resides.
  • NODE_COUNT: the number of read pool nodes you want in the read pool. Choose any number from1 to20.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_POOL_NAME

Request JSON body:

{  "nodeCount":NODE_COUNT}

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 runninggcloud 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 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/instances/READ_POOL_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_POOL_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/instances/READ_POOL_NAMEINSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "READ_POOL_NAME",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

Edit read pool configuration

The following steps show you how to edit read pool configuration. For moredetailed information, seeAbout instance settings andEdit instances.

gcloud

For information about installing and getting started with the gcloud CLI, seeInstall the gcloud CLI. For information about starting Cloud Shell, seeUse Cloud Shell.

Use the followinggcloud sql instances patch command to vertically scale the read pool, for example, by modifying the machine type:

gcloudsqlinstancespatchREAD_POOL_NAME\--tier=TIER

Make the following replacements:

  • READ_POOL_NAME: the name of the read pool.
  • TIER: the machine type you want to apply to each read pool node in the read pool, such asdb-perf-optimized-N-8.

Terraform

To edit the read pool configuration, update an existingTerraform resource. The manifest looks similar to the one you used inCreate a read pool. Then, update the attributes you want to change in thesettings field. For example, change thesettings.tier attribute to a different machine type.

REST v1

Use thepatch method to modify read pool node configuration. Settings are uniformly applied across all read pool nodes in the read pool.

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

  • PROJECT: the name of the project where the read pool resides.
  • TIER: the machine type you want to use for each read pool node in the read pool, such asdb-perf-optimized-N-4.
  • READ_POOL_NAME: the name of the read pool, such asmy-read-pool.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_POOL_NAME

Request JSON body:

{  "settings": {    "tier": "TIER"  }}

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 runninggcloud 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 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/instances/READ_POOL_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_POOL_NAME" | 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/instances/READ_POOL_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "READ_POOL_NAME",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

REST v1beta4

Use thepatch method to modify read pool node configuration. Settings are uniformly applied across all read pool nodes in the read pool.

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

  • PROJECT: the name of the project where the read pool resides.
  • TIER: the machine type you want to use for each read pool node in the read pool, such asdb-perf-optimized-N-4.
  • READ_POOL_NAME: the name of the read pool, such asmy-read-pool.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_POOL_NAME

Request JSON body:

{  "settings": {    "tier": "TIER"  }}

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 runninggcloud 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 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/instances/READ_POOL_NAME"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_POOL_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/instances/READ_POOL_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "UPDATE",  "name": "OPERATION_ID",  "targetId": "READ_POOL_NAME",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

Connect to a read pool

There are many ways to connect to a read pool. The following steps show oneway, namely, connecting to a read pool with a private IP address by creating aVM in the same VPC network to serve as the connection source.

For more information about other ways you can configure connectivity to aCloud SQL instance, seeAbout Cloud SQL connections.The connection methods usually require you to first obtain the IP address orconnection name of the instance, as described inView read pool information.Read pools support most of the connection methods available for other Cloud SQLinstances, with somelimitations.

If connecting using the Cloud SQL Auth Proxy or the Cloud SQL Connectors, make sure to updateto the latest version. For read pool support, the minimum required versionsinclude the following:

  • Cloud SQL Auth Proxy: v2.15.2
  • Cloud SQL Python Connector: v1.18.0
  • Cloud SQL Go Connector: v1.16.0
  • Cloud SQL Node Connector: v1.7.0
  • Cloud SQL Java Connector: v1.24.0

Console

To connect to a read pool, complete the following steps:

  1. In the Google Cloud console, go to theCloud SQL Instances page.

    Go to Cloud SQL Instances

    You're taken to the instance Overview page. Click into the new read pool to view the details including its private IP address. In theConnect to this instance section, copy and save the instance'sConnection name. Theconnection name is in the formatprojectID:region:instanceID. You'll use thisconnection name later when starting the Cloud SQL Auth Proxy.
  2. Create a Compute Engine VM.
  3. Open two SSH connections to the Compute Engine VM. These are used in subsequent steps to run the Cloud SQL Auth Proxy and run the database client.
  4. Install the client.
  5. Install the Cloud SQL Auth Proxy.
  6. Start the Cloud SQL Auth Proxy.
  7. Connect to your Cloud SQL instance.

For more information, seeConnect to a Cloud SQL instance with private IP.

Delete a read pool

gcloud

For information about installing and getting started with the gcloud CLI, seeInstall the gcloud CLI. For information about starting Cloud Shell, seeUse Cloud Shell.

Use the followinggcloud sql instances delete command to delete a read pool:

gcloudsqlinstancesdeleteREAD_POOL_NAME

Make the following replacements:

  • READ_POOL_NAME: the name of the read pool you want to delete.

REST v1

Use thedelete method to delete a read pool.

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

  • PROJECT: the name of the project where the read pool resides.
  • READ_POOL_NAME: the name of the read pool, such asmy-read-pool.

HTTP method and URL:

DELETE https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_POOL_NAME

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 runninggcloud 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.

Execute the following command:

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

PowerShell (Windows)

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

Execute the following command:

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

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT/instances/READ_POOL_NAME" | 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/instances/READ_POOL_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "DELETE",  "name": "OPERATION_ID",  "targetId": "READ_POOL_NAME",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

REST v1beta4

Use thedelete method to delete a read pool.

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

  • PROJECT: the name of the project where the read pool resides.
  • READ_POOL_NAME: the name of the read pool, such asmy-read-pool.

HTTP method and URL:

DELETE https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_POOL_NAME

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 runninggcloud 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.

Execute the following command:

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

PowerShell (Windows)

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

Execute the following command:

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

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/instances/READ_POOL_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/instances/READ_POOL_NAME",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-21T22:43:37.981Z",  "operationType": "DELETE",  "name": "OPERATION_ID",  "targetId": "READ_POOL_NAME",  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT/operations/OPERATION_ID",  "targetProject": "PROJECT"}

What's next

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-11-24 UTC.