Create and manage read pools

MySQL  |  PostgreSQL  |  SQL Server

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. You can process personal data for this feature as outlined in theCloud Data Processing Addendum, subject to the obligations and restrictions described in the agreement under which you access Google Cloud. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

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 v516.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 beta sql instances create command to create a read pool with multiple read pool nodes:

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

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,MYSQL_8_0_37.
  • 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,MYSQL_8_0_37.
  • 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 beta sql instances patch command to convert a read replica for use with a read pool:

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

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 beta sql instances patch command to convert a read replica for use with a read pool:

gcloudbetasqlinstancespatchREAD_POOL_NAME\--instance-type=READ_REPLICA_INSTANCE

Make the following replacements:

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

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"}

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"}

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 beta sql instances describe command to describe the read pool:

gcloudbetasqlinstancesdescribeREAD_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 beta sql instances patch command to scale the read pool:

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

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 beta sql instances patch command to vertically scale the read pool, for example, by modifying the machine type:

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

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-07-14 UTC.