Upgrade an instance to the new network architecture

MySQL   |  PostgreSQL   |  SQL Server

This page describes how to upgrade your Cloud SQL instances from the old network architecture to the new network architecture.

This Cloud SQL network architecture upgrade page applies only to some Cloud SQL instances. If your Cloud SQL instances use a Virtual Private Cloud (VPC) network project that was created before August 2021, then you need to upgrade the Cloud SQL network architecture for your instances.

Overview

The following table shows the benefits of new network architecture compared to the old network architecture:

Capability	Old network architecture	New network architecture
Migrating from Cloud SQL to AlloyDB for PostgreSQL and from AlloyDB for PostgreSQL to Cloud SQL using Database Migration Service	Requires that you configure a private IP address for the migration	No additional network configuration required. For example, Cloud SQL to AlloyDB for PostgreSQL migration or AlloyDB for PostgreSQL to Cloud SQL migration.
Connect your Cloud SQL instance by using private IP to private services such as Cloud Build or Vertex AI	Not supported due to network peering intransitivity	Supported
Instances that are compliant with Assured Workloads	Not supported	Supported
Managed Microsoft AD	Not supported	Supported
Private Service Connect	Not supported	Supported
IP address range usage	Extra IP address ranges consumed for dedicated subnets for Cloud SQL for PostgreSQL private IP instances	No extra IP address ranges consumed for Cloud SQL for PostgreSQL instances
Default Cloud SQL instance quota per project	100	1000

Plan your upgrade

Before you upgrade the network architecture of your Cloud SQL instances, plan the upgrade according to the following upgrade constraints:

• Upgrading your network architecture will incur approximately two minutes of database downtime.

• If there's an ongoing data migration, then you can't upgrade the source instance to the new architecture during the data migration.

• If for the past four days or less, there are two or more instances in your network in the same region, then you can upgrade only those instances that have high availability enabled.

  Note: In this scenario, Cloud SQL uses an extra /24 range temporarily to host your upgraded instances on the new architecture. After Cloud SQL upgrades all of the instances in the network and region combination, Cloud SQL releases the range.

  For example, if your network contains two instances and one is in us-east1 and the other is in us-central1, then you can upgrade both instances, regardless of whether high availability is enabled or not. However, if your network contains three instances and one is in us-east1 and the other two are in us-central1, then you can upgrade the instances in us-central1 that have high availability enabled. Because the instance in us-east1 is the only instance in that region, you can upgrade it, regardless of whether high availability is enabled.

• Once you upgrade a high availability instance to the new network architecture, you can't disable high availability on that instance.

Plan to upgrade all Cloud SQL instances in a network project

Your Cloud SQL instances can be in the same project as the VPC network or they can be hosted in a separate project. The project that hosts the VPC network is the network project.

If at least one Cloud SQL instance within a network project uses the old network architecture, then the entire project uses the old network architecture. In this case, your project isn't fully upgraded to the new network architecture.

You can use the gcloud CLI or the Cloud SQL Admin API to query the network architecture for all your Cloud SQL instances within a project.

When you modify an instance's private network or you enable private IP for an instance, you can't modify the network architecture in the same request. If you do, the request is rejected. To avoid this, we recommend that you upgrade all instances in a network project before modifying the network project.

Upgrade your Cloud SQL network architecture

To upgrade the network architecture of your Cloud SQL instances, do the following:

1. Check the network architecture of either a single Cloud SQL instance or multiple Cloud SQL instances.
2. Upgrade the network architecture of a Cloud SQL instance.

Check the network architecture of a single Cloud SQL instance

To check the current network architecture of a single instance, use the gcloud sql instances describe command or the instances.get method.

gcloud

For information about installing and getting started with the gcloud CLI, see Install the gcloud CLI. For information about starting Cloud Shell, see Use Cloud Shell.

To check the network architecture of a single instance, run the following command:

   gcloud sql instances describe INSTANCE_NAME
   

If the instance uses the old network architecture, then the response is similar to the following:

   name: INSTANCE_NAME
   project: PROJECT_ID
   ...
   sql_network_architecture: OLD_NETWORK_ARCHITECTURE
  

If the instance uses the new network architecture, then the response is similar to the following:

   name: INSTANCE_NAME
   project: PROJECT_ID
   ...
   sql_network_architecture: NEW_NETWORK_ARCHITECTURE
  

The sql_network_architecture parameter indicates whether your instance uses the old network architecture (OLD_NETWORK_ARCHITECTURE) or the new network architecture (NEW_NETWORK_ARCHITECTURE).

REST v1

To check the network architecture of an instance, use the instances.get method of the Cloud SQL Admin API.

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

• PROJECT_ID: The project ID.
• INSTANCE_NAME: The instance name.
• NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
  • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
  • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL:

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

Request JSON body:

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

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 the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

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

PowerShell (Windows)

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

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

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

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

You should receive a JSON response similar to the following:

{
  "kind": sql#instance
  "name": INSTANCE_NAME
  "project": PROJECT_ID
  "sqlNetworkArchitecture": enum (SqlNetworkArchitecture)
  ...
}

REST v1beta4

To check the network architecture of an instance, use the instances.get method of the Cloud SQL Admin API.

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

• PROJECT_ID: The project ID.
• INSTANCE_NAME: The instance name.
• NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
  • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
  • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL:

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

Request JSON body:

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

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 the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

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

PowerShell (Windows)

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

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

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

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

You should receive a JSON response similar to the following:

{
  "kind": sql#instance
  "name": INSTANCE_NAME
  "project": PROJECT_ID
  "sqlNetworkArchitecture": enum (SqlNetworkArchitecture)
  ...
}

Check the network architecture of multiple Cloud SQL instances

To check the network architecture of multiple instances in a project, use the gcloud sql instances list command or the instance.list method.

gcloud

To check the network architecture of multiple instances in a project, run the following command:

gcloud sql instances list --show-sql-network-architecture

The output looks similar to the following.

NAME        DATABASE_VERSION LOCATION   ...     SQL_NETWORK_ARCHITECTURE
instance_1  POSTGRES_13      asia-northeast1-b  OLD_NETWORK_ARCHITECTURE
instance_2  MYSQL_5_7        europe-west1-d     NEW_NETWORK_ARCHITECTURE
...

REST v1

To check the network architecture of multiple instances in a project, use the instance.list method.

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

• PROJECT_ID: The project ID.
• NETWORK_ARCHITECTURE_TYPE: The network architecture type as follows:
  • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
  • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL:

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

Request JSON body:

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

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 the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

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

PowerShell (Windows)

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

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

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

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

You should receive a JSON response similar to the following:

{
  "kind": sql#instance
  "name": INSTANCE_NAME
  "project": PROJECT_ID
  "sqlNetworkArchitecture": enum (SqlNetworkArchitecture)
  ...
}

REST v1beta4

To check the network architecture of multiple instances in a project, use the instance.list method.

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

• PROJECT_ID: The project ID.
• NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
  • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
  • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL:

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

Request JSON body:

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

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 the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

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

PowerShell (Windows)

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

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

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

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

You should receive a JSON response similar to the following:

{
  "kind": sql#instance
  "name": INSTANCE_NAME
  "project": PROJECT_ID
  "sqlNetworkArchitecture": enum (SqlNetworkArchitecture)
  ...
}

Upgrade the network architecture of a single Cloud SQL instance

To upgrade the network architecture for a single instance, use the gcloud sql instances patch command, the instance.update method, or the instance.patch method.

gcloud

To upgrade the network architecture of an instance, run the following command:

gcloud sql instances patch INSTANCE_NAME --upgrade-sql-network-architecture

The upgrade operation takes approximately a few minutes.

During the upgrade, a long-running operation starts, and an operation token is returned:

operation_id

REST v1

To upgrade the network architecture of an instance, use the instance.update or the instance.patch method of the Cloud SQL Admin API.

When you upgrade the Cloud SQL network architecture, no additional updates to the instance are allowed in the request. The request body contains an instance of the DatabaseInstance object, with sqlNetworkArchitecture set to NEW_NETWORK_ARCHITECTURE.

During the upgrade, a long-running operation starts, and an operation token is returned:

operation_id

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

• PROJECT_ID: The project ID.
• INSTANCE_NAME: The instance name.
• NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
  • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
  • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL:

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

Request JSON body:

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

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 the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

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

PowerShell (Windows)

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

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

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

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

You should receive a JSON response similar to the following:

{
  "kind": sql#instance,
  "targetLink": string,
  "status": enum (SqlOperationStatus),
  "name": string,
  "insertTime": string,
  "startTime": string,
  "endTime": string
  ...
}

If the upgrade of your instance fails, then retry the upgrade operation.

REST v1beta4

To upgrade the network architecture of an instance, use the instance.update method or the instance.patch method of the Cloud SQL Admin API.

When you upgrade the Cloud SQL network architecture, no additional updates to the instance are allowed in the request. The request body contains an instance of the DatabaseInstance object, with sqlNetworkArchitecture set to NEW_NETWORK_ARCHITECTURE.

During the upgrade, a long running operation starts, and the following operation token is returned:

operation_id

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

• PROJECT_ID: The project ID.
• INSTANCE_NAME: The instance name.
• NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
  • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
  • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL:

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

Request JSON body:

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

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 the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.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/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

PowerShell (Windows)

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

Save the request body in a file named request.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/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "kind": sql#instance,
  "targetLink": string,
  "status": enum (SqlOperationStatus),
  "name": string,
  "insertTime": string,
  "startTime": string,
  "endTime": string
  ...
}

If the upgrade of your instance fails for any reason, you can retry the upgrade operation.

Frequently asked questions

This section provides answers to frequently asked questions about upgrading your Cloud SQL network architecture.

What's the impact of the upgrade on my Cloud SQL instance?

When upgrading your network architecture, the Cloud SQL instance has a MAINTENANCE state. In this state, the instance experiences up to three minutes of downtime and any additional changes to the instance aren't allowed until the upgrade is complete. Other instances in your project or network won't be affected by the upgrade.

Do all features work the same after the upgrade?

All features of your Cloud SQL instance work the same on the new architecture as they did on the old architecture. After you upgrade an instance to use the new network architecture, if you want to switch the network of that instance, then make sure that all instances in the destination network are also upgraded to the new network architecture.

Which instances use the old network architecture?

Any new projects that were created after August, 2021 automatically use the new network architecture. Existing projects can contain Cloud SQL instances that are older than two years and still use the old network architecture. Therefore, all instances within an existing project must be upgraded before any new instances in that project can start using the new network architecture.

Are all new Cloud SQL instances created on the new network architecture?

By default, new Cloud SQL instances created in projects created after August, 2021 use the new network architecture. If you want to create an instance in a project created before August, 2021, and use the new network architecture, you must do the following:

1. Update all of your existing instances in that project to the new network architecture.

2. If you have a Google Cloud support contract, create a support request to change the default network architecture of the project to the new architecture.

3. If you don't have a support contract, create your instance and then upgrade it to the new network architecture.

After the project's default is changed, you can create instances with the new network architecture in that project.

If you don't change the default network architecture of your project, all new instances in that project will use the old network architecture. You must then individually upgrade each of these instances to the new network architecture.

Is it possible to update all instances in a project with a single command?

No, the upgrade to the new network architecture is based on each instance.

Does the replica automatically get upgraded if I upgrade the primary?

No, the upgrade to the new network architecture is based on each individual instance. Each replica is treated as a separate instance and must be upgraded separately. This means that if the primary is upgraded and the replica is using the old network architecture, the replica isn't affected. The opposite is also true. If you upgrade a replica, the primary won't be affected.

What's next

• Read more about Private Service Connect
• Read more about Assured Workloads
• Read more about Configure private service access for Cloud SQL
• Read more about Database migration service to AlloyDB for PostgreSQL