Upgrade an instance to the new network architecture

MySQL | PostgreSQL | SQL Server

Important: The command for upgrading Cloud SQL instances to the newnetwork architecture is temporarily disabled.

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

This Cloud SQL network architecture upgrade page applies only to someCloud 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 upgradethe Cloud SQL network architecture for your instances.

Overview

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

Capability	Old network architecture	New network architecture
Migrating from Cloud SQL to AlloyDB for PostgreSQL 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.
Connect your Cloud SQL instance by using private IP toprivate services such as Cloud Build or Vertex AI	Not supported due to network peering intransitivity	Supported
Instances that are compliant withAssured 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 SQLinstance quota per project	100	1000

Plan your upgrade

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

If you upgrade your network architecture, then you can expect downtime onyour instance of up to 4 minutes on average.
If there's an ongoing data migration, then you can't upgrade the sourceinstance to the new architecture during the data migration.
If youconnect to an instance from an external source,then verify that all peering connections are updated to enable the export of custom routes.
If you're usingservice perimeters,then verify thatShared VPC host project is included.If this project isn't included, then the migration fails.
You can't upgrade the network architecture of instances on a network withmore than 300 Cloud SQL instances.

If your network includes two or more instances that use private IP addressesin the same region, then Cloud SQL must use an additional /24 range (or ranges)from your allocated private services access IP address rangeto host the instances in the new network architecture.This additional consumption is temporary,and is removed during a subsequent Cloud SQL maintenance event.

Plan to upgrade all Cloud SQL instances in a network project

Your Cloud SQL instances can reside either in the same project as theVPC network or in a separate project. The project hosting theVPC network is thenetwork project.

A network project can operate indual stack mode, meaning that it can hostCloud SQL instances simultaneously, using both the old and new network architectures. This occurs when at least one instance within the project usesthe old architecture. As a result, Cloud SQL can't upgrade the projectto the new architecture.

To query the network architecture for all instances within a project,you can use gcloud CLI or the API.

Considerations for dual stack projects

When using dual stack projects, keep in mind the following considerations:

Upgrade an instance implicitly: When you modify an instance's privatenetwork or enable the private IP address within a dual stack project, Cloud SQLmight upgrade the instance to the new network architecture implicitly.
No architecture downgrades: Network changes never downgrade an instance'snetwork architecture.
Reject requests: If a network change needs a downgrade to complete, thenCloud SQL rejects the request.
New instances can't use IP ranges from the old network architecture: Whena project is in dual stack mode, you can't create instances that use IP rangesthat are associated with service connections from the old network architecture.
New network architecture enforcement: You can force an instance to usethe new network architecture when youcreate the instance or you modifyitsnetwork configuration.When you use the--enforce-new-network-architectureflag to create or update the instance, the instance is placed in aseparate subnet from instances that use the old network architecture.The separation is permanent and persists even after you upgradethe old network architecture instances to the new network architecture.
For more details on IP allocation and subnets, seeAllocated IP address ranges.

To avoid potential conflicts and to ensure a smooth network upgrade, we recommend thatyou plan to upgrade all instances in the project to the new architecture.

Upgrade your Cloud SQL network architecture

To upgrade the network architecture of yourCloud SQL instance, do the following:

Check the network architecture of eithera single Cloud SQL instance ormultiple Cloud SQL instances.
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 thegcloud sql instances describe command or theinstances.get method.

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.

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

   gcloud sql instances describeINSTANCE_NAME

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

name:INSTANCE_NAMEproject:PROJECT_ID...sqlNetworkArchitecture:OLD_NETWORK_ARCHITECTURE

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

name:INSTANCE_NAMEproject:PROJECT_ID...sqlNetworkArchitecture:NEW_NETWORK_ARCHITECTURE

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

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

curl -X 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 thegcloud CLI with your user account by running gcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

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

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

Invoke-WebRequest `
    -Method 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 theinstances.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)

Save the request body in a file namedrequest.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)

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 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 thegcloud sql instances list command or theinstance.list method.

gcloud

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

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

The output looks similar to the following.

NAMEDATABASE_VERSIONLOCATION...SQL_NETWORK_ARCHITECTUREinstance_1POSTGRES_13asia-northeast1-bOLD_NETWORK_ARCHITECTUREinstance_2MYSQL_5_7europe-west1-dNEW_NETWORK_ARCHITECTURE...

REST v1

To check the network architecture of multiple instances in a project, use theinstance.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)

Save the request body in a file namedrequest.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)

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 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 theinstance.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)

Save the request body in a file namedrequest.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)

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 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 thegcloud sql instances patch command, theinstance.update method, or theinstance.patchmethod.

gcloud

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

gcloud sql instances patchINSTANCE_NAME --upgrade-sql-network-architecture

The upgrade operation takes a few minutes.

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

operation_id

REST v1

To upgrade the network architecture of an instance, use theinstance.updateor theinstance.patchmethod of the Cloud SQL Admin API.

When you upgrade the Cloud SQL network architecture, no additionalupdates to the instance are allowed in the request. The request body contains aninstance of theDatabaseInstanceobject, withsqlNetworkArchitecture set toNEW_NETWORK_ARCHITECTURE.

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

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)

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

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

PowerShell (Windows)

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

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

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/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 upgradeoperation.

REST v1beta4

To upgrade the network architecture of an instance, use theinstance.update methodor theinstance.patch methodof the Cloud SQL Admin API.

During the upgrade, a long running operation starts, and the followingoperation 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/sql/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)

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

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

PowerShell (Windows)

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

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

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/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 upgradeoperation.

Frequently asked questions

This section provides answers to frequently asked questions aboutupgrading 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 aMAINTENANCE state. In this state, the instance experiences up to four minutesof downtime, on average. Any additional changes to the instance aren't alloweduntil the upgrade is complete. Other instances in your project or network aren'taffected by the upgrade.

Do all features work the same after the upgrade?

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

Which instances use the old network architecture?

Any new projects that were created after August, 2021 automatically usethe new network architecture. Existing projects can contain Cloud SQLinstances that are created before August 2021 and still use the old networkarchitecture. Therefore, all instances within an existing project must beupgraded before any new instances in that project can start using the newnetwork architecture.

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

By default, new Cloud SQL instances created in projects created afterAugust 2021 use the new network architecture.

If you want to create an instancein a project created before August 2021 and use the new network architecture,then you have the following options:

Update all existing instances: Update all of the existinginstances in the project to the new network architecture.If you're usingShared VPC,then you must update all instances in the projects that are participatingin the Shared VPC. After you've updated all of theexisting instances in the project, wait several hours before youcreate additional instances in the project. New instances thatyou create in the project will then use the new network architecture.
Enforce the use of the new network architecture: You can forceCloud SQL use the new network architecture by using thesqlNetworkArchitecture field in the API or the--enforce-new-network-architecture flag in thegcloud CLI when youcreate an instance ormodify the private IP network configuration of an existing instance.However, when you enforce new network architecture for instances beforea project is fully upgraded, you might experience instance creationfailure if sufficient IP address space isn't available.For more details on IP address range allocation,seeAllocated IP address ranges.

If there are recently deleted instances with the old network architecture, youneed to wait four days before creating a new instance with the new networkarchitecture. This delay accommodates the process torestorea deleted instance.

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 individualinstance. Each replica is treated as a separate instance and must be upgradedseparately. This means that if the primary is upgraded and the replica isusing the old network architecture, the replica isn't affected.The opposite is also true. If you upgrade a replica, the primary won't beaffected.

I received a notification that the network architecture of my Cloud SQL instances will be upgraded. What do I need to do?

No action is required by you.

For some instances, when the automatic upgrade occurs on a private network, therequest is temporarily rejected. As a workaround, you can upgrade the networkarchitecture of your instance yourself by following the procedure inUpgrade the network architecture of a single Cloud SQL instance.

When I attempt to upgrade my instance, I receive the error "outside the reserved IP address range". What do I need to do?

To use Cloud SQL instances in a VPC network withprivate IP, allocate IP address ranges when you set upprivate services access for the VPC network.

For example, if an IP allocated address range is changed or deleted,then you might encounter an error similar to the following:

Network architecture upgrade not allowed for private-ip instancePROJECT_ID:INSTANCE_NAMEwhose IP address range10.0.0.0/24 is outside the reserved IP address range forprivate services access. Re-allocate the IP address range for private services access and retry.

In this example, the original allocated IP address range has thenamegoogle-managed-services-VPC_NETWORK_NAME, and the originalallocated IP address range is10.0.0.0/16.Then you create an instance with a private IP address of10.0.0.1.If the IP address range ofgoogle-managed-services-VPC_NETWORK_NAME is deleted,or is updated to refer to a range of10.1.0.0/16this range doesn't cover the instance's private IP address10.0.0.1.Afterwards, when you try to upgrade the network architecture of your instance,you encounter theoutside the reserved IP address range error.

To resolve this issue, follow the procedure inConfigure private services access for Cloud SQL.Re-allocate an IP address range that includes the IP address ofyour instance into the ranges allocated for private services access.At the least, you can allocate the IP address range reported in yourerror message (in the previous example,10.0.0.0/24.)

Then retry the network architecture upgrade.

What's next

Read more aboutPrivate Service Connect
Read more aboutAssured Workloads
Read more aboutConfigure private service access for Cloud SQL
Read more aboutDatabase migration service to AlloyDB for PostgreSQL

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-03 UTC.

Movatterモバイル変換

Upgrade an instance to the new network architecture

Overview

Plan your upgrade

Plan to upgrade all Cloud SQL instances in a network project

Considerations for dual stack projects

Upgrade your Cloud SQL network architecture

Check the network architecture of a single Cloud SQL instance

gcloud

REST v1

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

REST v1beta4

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Check the network architecture of multiple Cloud SQL instances

gcloud

REST v1

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

REST v1beta4

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Upgrade the network architecture of a single Cloud SQL instance

gcloud

REST v1

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

REST v1beta4

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Frequently asked questions

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

Do all features work the same after the upgrade?

Which instances use the old network architecture?

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

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

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

I received a notification that the network architecture of my Cloud SQL instances will be upgraded. What do I need to do?

When I attempt to upgrade my instance, I receive the error "outside the reserved IP address range". What do I need to do?

What's next