Upgrade in place

MySQL   |  PostgreSQL   |  SQL Server

This page describes how to perform in-place upgrades and downgrades of your Cloud SQL instances.

Make in-place changes to a Cloud SQL instance

You can use in-place changes to upgrade or downgrade the edition of your Cloud SQL instance, its machine type, storage type, or database version. Making in-place changes is the easiest and least error-prone way to re-configure an instance.

Before you begin

Ensure that your instance is running on PostgreSQL 12 or later.

If your instance is on an earlier version of PostgreSQL, then you must upgrade to PostgreSQL 12 or later. For more information, see Upgrade the database major version in-place.

Be aware of potential storage changes related to machine type

Different editions support different machine types which use different storage options. High-performance C4 and C4A machine types use Hyperdisk Balanced storage rather than one of the persistent disk options used by older machine types.

When you make a change to the edition or machine type you're using, your storage type may also change, which may result in some downtime and a change in storage costs. When moving to Google Cloud Hyperdisk Balanced, there are additional configuration options that you can specify. For more information, see Storage changes.

Be aware of PITR transaction log storage changes

If you're upgrading a Cloud SQL Enterprise edition instance that stores the write-ahead logs used for PITR on disk, be aware that the upgrade process to Cloud SQL Enterprise Plus edition moves the storage location of those logs from disk to Cloud Storage. To determine the current location of PITR write-ahead logs for your instance, see Check the storage location of transaction logs used for PITR.

For a full explanation of how in-place upgrades can affect the location of the write-ahead logs, see Changes in storage location of write-ahead logs for PITR.

Change the edition of an instance in place

This section shows you how to change the edition of your Cloud SQL instance in place to or from Cloud SQL Enterprise Plus edition. Cloud SQL Enterprise Plus edition offers some benefits and performance enhancements that Cloud SQL Enterprise edition does not. For more information about Cloud SQL editions, see Cloud SQL editions overview.

Upgrading to Cloud SQL Enterprise Plus edition takes a few minutes to complete and has near-zero downtime. Switching back to Cloud SQL Enterprise edition will result in a longer downtime. Neither process requires changing the endpoints that your applications connect to.

Use the procedure in this section to upgrade a Cloud SQL Enterprise edition instance to Cloud SQL Enterprise Plus edition, or to downgrade a Cloud SQL Enterprise Plus edition instance to Cloud SQL Enterprise edition.

Console

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

   Go to Cloud SQL Instances

2. To open the Overview page of an instance, click the instance name.
3. Click Edit.
4. In the Choose a Cloud SQL edition section, click Upgrade if your instance is using the Cloud SQL Enterprise edition, or Switch to Enterprise if your instance is using Cloud SQL Enterprise Plus edition.
5. Use the panel that opens to specify the configuration of your instance using the new edition. See [Options when making in-place changes](#change-options).
6. Enter your instance ID to confirm these choices and then click either Upgrade edition or Switch edition depending on whether you're upgrading or downgrading.

You can also start an edition change in the Instances page if you select Edit in the Actions column of the instance.

In addition, if your instance is on Cloud SQL Enterprise edition, you can start an upgrade by clicking the Upgrade link beside the edition field in the Configuration section of the instance page.

gcloud

The following [`gcloud sql instance patch`](/sdk/gcloud/reference/sql/instances/patch) code sample shows how to upgrade your instance to Cloud SQL Enterprise Plus edition:

gcloud sql instances patch INSTANCE_ID \
  --edition=enterprise-plus \
  --tier=MACHINE_TYPE \
  --project=PROJECT_ID

Optional: you can also enable data cache for your instance by adding the --enable-data-cache flag.

Replace the following:

• PROJECT_ID: the project ID of the instance that you want to upgrade.
• INSTANCE_ID: name of the instance that you want to upgrade.
• MACHINE_TYPE: the machine type of the instance that you want to upgrade to. For more information about machine types for Cloud SQL Enterprise Plus edition, see Machine types for Cloud SQL Enterprise Plus edition instances.

REST

The following command upgrades your instance to Cloud SQL Enterprise Plus edition and triggers a restart operation.

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

• PROJECT_ID: the project ID of the instance that you want to upgrade.
• INSTANCE_ID: the instance ID of the instance that you want to upgrade.
• MACHINE_TYPE: the machine type of the instance that you want to upgrade to. For more information about machine types for Cloud SQL Enterprise Plus edition, see Machine types for Cloud SQL Enterprise Plus edition instances.

Optional: you can enable data cache by setting the dataCacheEnabled parameter as true.

HTTP method and URL:

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

Request JSON body:

{
  "settings": {
      "tier": "MACHINE_TYPE",
      "edition": "ENTERPRISE_PLUS",
      "dataCacheConfig": {
        "dataCacheEnabled": true
      },
  }
}

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

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_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

The following command upgrades your instance to Cloud SQL Enterprise Plus edition and triggers a restart operation.

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

• PROJECT_ID: the project ID of the instance that you want to upgrade.
• INSTANCE_ID: the instance ID of the instance that you want to upgrade.
• MACHINE_TYPE: the machine type of the instance that you want to upgrade to. For more information about machine types for Cloud SQL Enterprise Plus edition, see Machine types for Cloud SQL Enterprise Plus edition instances.

Optional: you can enable data cache by setting the dataCacheEnabled parameter as true.

HTTP method and URL:

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

Request JSON body:

{
  "settings": {
      "tier": "MACHINE_TYPE",
      "edition": "ENTERPRISE_PLUS",
      "dataCacheConfig": {
        "dataCacheEnabled": true
      },
  }
}

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

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_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Options for in-place changes

Changing the edition of your Cloud SQL instance can require changing its machine series, which in turn affects its storage type.

Machine changes

When you change editions, you have to change machine type, too. See Choose a machine series for more information about the machine series that Cloud SQL supports.

When upgrading from Cloud SQL Enterprise edition to Cloud SQL Enterprise Plus edition, you can choose between the N2, C4A, and C4 machine series.

When downgrading from Cloud SQL Enterprise Plus edition to Cloud SQL Enterprise edition, you can choose between a general purpose dedicated-core, and an N4 machine series.

Note: You cannot downgrade back to a Cloud SQL Enterprise edition general-purpose shared core machine series.

You can also change machine type without changing edition. After choosing to edit your instance, go to the Machine sub-section of Machine Configuration in the Customize your instance area. Using the drop-down, you can select a different machine type. You can also choose a different number of VCPUs, and enable or disable the data cache if appropriate.

For more general information, see also Compute Engine documentation for the N2, C4A, C4, and N4 machine series.

Storage changes

If you are changing from a general purpose or an N2 machine series to an N4, C4A, or C4 machine series, your storage will be migrated from Solid-state drive (SSD) to Google Cloud Hyperdisk balanced storage. This upgrade generally requires minimal downtime.

Important: If you switch from an N4, C4, or C4A machine series back to a general purpose dedicated-core or N2 machine series, moving your data from Google Cloud Hyperdisk Balanced storage to solid-state drive (SSD) storage can incur significant downtime. You cannot move to or from Hard-disk drive (HDD) storage.

Google Cloud Hyperdisk Balanced storage can be customized for your use case by setting the following:

• Storage capacity
• Provisioned IOPS
• Provisioned throughput

Google Cloud Hyperdisk Balanced sets default IOPS and throughput values and limits based on your instance's configuration, which includes the machine type and storage capacity. Storage capacity limits the default value, and the machine type sets the maximum value for both IOPS and throughput. See Choose a storage option for details.

Location changes of write-ahead logs for PITR

If your Cloud SQL Enterprise edition instance stores transaction logs for PITR on disk, then starting the upgrade process to Cloud SQL Enterprise Plus edition switches the storage location of these logs to Cloud Storage.

The following conditions apply to the location change:

• The process takes approximately the duration of the transactionLogRetentionDays PITR configuration setting to complete the switch to Cloud Storage.
• During the switch to Cloud Storage, we recommend that you don't modify the transactionLogRetentionDays PITR configuration setting. Even if you do increase transactionLogRetentionDays, write-ahead logs won't be retained on disk any longer than the default of 7 days for a Cloud SQL Enterprise edition instance.

Cloud SQL Enterprise Plus edition backup and log storage defaults

Changing to Cloud SQL Enterprise edition doesn't switch the storage location of the transaction logs used for PITR. If your Cloud SQL Enterprise Plus edition instance stores its transaction logs for PITR in Cloud Storage, then the logs remain in Cloud Storage. However, instead of storing 14 days of transaction logs for PITR by default, the default is changed to 7 days. Backup configuration is not changed.