Upgrade the database minor version

This page describes how to set the database minor version of an instance. For supported versions, see Database versions and version policies.

With each new minor version, database providers release new features, security patches, bug fixes, and performance improvements. Additionally, Cloud SQL regularly updates your minor version during maintenance.

However, MySQL 8.0 doesn't support downgrading. As such, minor version upgrades aren't automatically included with routine maintenance. You can specify the minor version for Cloud SQL for MySQL 8.0 while creating an instance or later through an upgrade process, both of which are described on this page.

Before upgrading to a new MySQL 8.0 minor version, familiarize yourself with the changes. See MySQL 8.0 Release Notes. If you use Cloud SQL for MySQL 5.6 or 5.7, Cloud SQL automatically manages your instance's minor version. When you provision a new instance, Cloud SQL automatically configures your instance with the latest database version available. During routine maintenance, Cloud SQL automatically upgrades your instance to the latest supported version.

To upgrade the database minor version of your MySQL 8.0 instance, you need to update your instance with your preferred minor version, which must be greater than the currently installed minor version. You cannot revert to an unspecified minor version after an instance has been provisioned.

Before you upgrade

MySQL 8.0 doesn't allow downgrades. So, before you upgrade your primary instance, follow these steps to ensure that your data is safe.

  1. Test your upgrade in a staging environment.

    1. Create a clone of your production instance to serve as a staging instance. This creates a new database instance, with the same major and minor versions.

    2. Perform a minor version upgrade on the staging instance.

    3. Run workload tests to verify that the upgrade was successful and that your application performs as expected. When testing is successful, proceed to upgrade your read replica instances.

  2. Upgrade your read replica instances.

    1. Upgrade all read replicas in the database to the target minor version.

    2. Verify that your application works as expected.

  3. Back up your primary instance.

    As with any significant database update, make a backup of your primary instance.

Upgrade the minor version

You can specify the database minor version of an existing instance by using gcloud or the REST API. Perform minor version upgrades at a time when the database isn't in use. The instance is restarted during the operation, which causes downtime. If the currently installed version is higher than the requested version, the request is rejected.

gcloud

Use the gcloud sql instances patch command with the --database-version flag.

Replace the following variables before running the command:

  • INSTANCE_NAME: The name of the instance.
  • DATABASE_VERSION: The database version of the instance. If you don't specify this flag, the default major version is used.
gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

REST v1

Use a PATCH request with the instances:patch method and the databaseVersion flag.

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

  • PROJECT-ID: The project ID
  • INSTANCE-ID: The instance ID
  • DATABASE_VERSION: The database version to upgrade to.

HTTP method and URL:

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT-ID/instances/INSTANCE-ID

Request JSON body:

{
  "databaseVersion": "DATABASE_VERSION"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://content-sqladmin.googleapis.com/v1/projects/PROJECT-ID/instances/INSTANCE-ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2022-07-17T20:23:15.540Z",
  "operationType": "UPDATE",
  "name": "fa3f7304-ccf6-4d2f-a6f5-24df00000032",
  "targetId": "INSTANCE-ID",
  "selfLink": "https://content-sqladmin.googleapis.com/v1/projects/PROJECT-ID/operations/fa3f7304-ccf6-4d2f-a6f5-24df00000032",
  "targetProject": "PROJECT-ID"
}

REST v1beta4

Use a PATCH request with the instances:patch method and the databaseVersion flag.

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

  • PROJECT-ID: The project ID
  • INSTANCE-ID: The instance ID
  • DATABASE_VERSION: The database version to upgrade to.

HTTP method and URL:

 https://sqladmin.googleapis.com/v1beta4/projects/PROJECT-ID/instances/INSTANCE-ID

Request JSON body:

{
  "databaseVersion": "DATABASE_VERSION"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "sql#operation",
  "targetLink": "https://content-sqladmin.googleapis.com/v1beta4/projects/PROJECT-ID/instances/INSTANCE-ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2022-07-17T20:23:15.540Z",
  "operationType": "UPDATE",
  "name": "fa3f7304-ccf6-4d2f-a6f5-24df00000032",
  "targetId": "INSTANCE-ID",
  "selfLink": "https://content-sqladmin.googleapis.com/v1beta4/projects/PROJECT-ID/operations/fa3f7304-ccf6-4d2f-a6f5-24df00000032",
  "targetProject": "PROJECT-ID"
}

Check the database minor installed version

When you view the instance summary information, the database minor installed version is visible in the Configuration section.

Roll back an upgrade

While testing an upgrade, if you notice an issue, you might want to roll back your database to recover the database instance running the previous minor version.

To restore a pre-upgrade backup, complete the following steps:

  1. Provision a recovery database instance on the previous minor version.
  2. Configure settings on the recovery database instance to the pre-upgrade state.
  3. Restore the pre-upgrade backup you took to the recovery instance.

As an alternative to restoring a backup, perform a point-in-time recovery and create a new instance.