Upgrade the database major version in-place

This page describes how to upgrade the database major version by upgrading your Cloud SQL instance in-place rather than by migrating data.


Database software providers periodically release new major versions that contain new features, performance improvements, and security enhancements. Cloud SQL intakes new versions after they're released. Once Cloud SQL offers support for a new major version, you can upgrade your instances to keep your database updated.

You can upgrade the database version of an instance in-place or by migrating data. In-place upgrades are a simpler way to upgrade your instance's major version. You don't need to migrate data or change application connection strings. With in-place upgrades, you can retain the name, IP address, and other settings of your current instance after the upgrade. In-place upgrades don't require you to move data files and can be completed faster. In some cases, the downtime is shorter than what migrating your data entails.

The Cloud SQL for the MySQL in-place upgrade operation uses the mysql_upgrade utility.

Plan a major version upgrade

  1. Choose a target major version.

    See the list of versions that Cloud SQL supports.

  2. Consider the features offered in each database major version and address incompatibilities.

    New major versions introduce incompatible changes that might require you to modify the application code, the schema, or the database settings. Before you can upgrade your database instance, review the release notes of your target major version to determine the incompatibilities that you need to address. If you're skipping major versions, address the incompatibilities listed for each version that you're skipping.

  3. Pre-check for upgrades from MySQL 5.7 to 8.0.

    Perform a pre-check before running upgrades from MySQL 5.7 to 8.0. You can use the Upgrade Checker Utility in MySQL shell. If any issues are found during the pre-check, fix them before proceeding to the upgrade. Cloud SQL doesn't support pre-checking during a major version upgrade. An attempt to upgrade an instance that has failed pre-checking might also fail.

  4. Check for disk space and instance machine types.

    A major version upgrade requires additional resources, such as disk space, to store upgraded tables. If the disk space isn't enough, the upgrade fails and rolls back. For an upgrade from MySQL 5.7 to 8.0, additional memory is required to convert old metadata to the new data dictionary. Before running a major version upgrade, ensure that you have more than 100K of memory for each table. You can temporarily increase the memory by changing the machine type.

  5. Test the upgrade with a dry run.

    Perform a dry run of the end-to-end upgrade process in a test environment before you upgrade the production database. You can clone your instance to create an identical copy of the data on which to test the upgrade process.

    In addition to validating that the upgrade completes successfully, run tests to ensure that the application behaves as expected on the upgraded database. If you haven't enabled automatic storage increases, take note of the disk storage used by the upgraded dry run instance to determine whether you need to increase the storage capacity for the production instance before upgrading.

  6. Decide on a time to upgrade.

    Upgrading requires the instance to become unavailable for a period of time. Plan to upgrade during a time period when database activity is low.

Upgrade the database major version in-place

When you initiate an upgrade operation, Cloud SQL first checks the configuration of your instance to ensure that it's compatible for an upgrade. After verifying your configuration, Cloud SQL makes your instance unavailable, makes a pre-upgrade backup, performs the upgrade, makes your instance available, and makes a post-upgrade backup.

When you upgrade to MySQL 8.0, Cloud SQL automatically provisions your instance on the default minor version.


  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 Instance info section, click the Upgrade button and confirm that you want to go to the upgrade page.
  5. On the Choose a database version page, click the Database version for upgrade list and select one of the available database major versions.
  6. Click Continue.
  7. In the Instance ID box, enter the name of the instance and then click the Start upgrade button.
The operation takes several minutes to complete.

Verify that the upgraded database major version appears below the instance name on the instance Overview page.


  1. Start the upgrade.

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

    Before running the command, replace the following:

    • INSTANCE_NAME: The name of the instance.
    • DATABASE_VERSION: The enum for the database major version, which must be greater than the current version. See the available database version enums.
    gcloud beta sql instances patch INSTANCE_NAME \

    Major version upgrades take several minutes to complete. You might see a message indicating that the operation is taking longer than expected. You can either ignore this message or run the gcloud sql operations wait command to dismiss the message.

  2. Get the upgrade operation name.

    Use the gcloud sql operations list command with the --instance flag.

    Before running the command, replace the INSTANCE_NAME variable with the name of the instance.

    gcloud sql operations list --instance=INSTANCE_NAME
  3. Monitor the status of the upgrade.

    Use the gcloud sql operations describe command.

    Before running the command, replace the OPERATION variable with the upgrade operation name retrieved in the previous step.

    gcloud sql operations describe OPERATION


  1. Start the in-place upgrade.

    Use a PATCH request with the instances:patch method.

    Before using any of the request data, replace these variables:

    • project_id: The ID of the project.
    • instance_name: The name of the instance.

    HTTP method and URL:

    POST https://sqladmin.googleapis.com/sql/v1/projects/project-id/instances/instance_name

    Request JSON body:

      "databaseVersion": enum DATABASE_VERSION

    Replace DATABASE_VERSION with the enum for the database major version, which must be greater than the current version. See the available database version enums.

    Send your request using curl or PowerShell. See Edit instances.

  2. Get the upgrade operation name.

    Use a GET request with the operations.list method after replacing project_id with the ID of the project.

    HTTP method and URL:

    GET https://sqladmin.googleapis.com/sql/v1/projects/project-id/operations
  3. Monitor the status of the upgrade.

    Use a GET request with the operations.get method after replacing the following variables:

    • project_id: The ID of the project.
    • operation_name: The upgrade operation name retrieved in the previous step.

    HTTP method and URL:

    GET https://sqladmin.googleapis.com/sql/v1/projects/project-id/operation/operation_name

When you place an in-place upgrade request, Cloud SQL first performs a pre-upgrade check. If Cloud SQL determines that your instance isn't ready for an upgrade, your upgrade request fails with a message suggesting how you can address the issue. See also Troubleshoot a major version upgrade.

Automatic upgrade backups

When you perform a major version upgrade, Cloud SQL automatically makes two on-demand backups, called upgrade backups:

  • The first upgrade backup is the pre-upgrade backup, which is made immediately before starting the upgrade. You can use this backup to restore your database instance to its state on the previous version.
  • The second upgrade backup is the post-upgrade backup, which is made immediately after new writes are allowed to the upgraded database instance.

When you view your list of backups, the upgrade backups are listed with type On-demand. Upgrade backups are labeled so that you can identify them easily. For example, if you're upgrading from MySQL 5.7 to MySQL 8.0, your pre-upgrade backup is labeled Pre-upgrade backup, MYSQL_5_7 to MYSQL_8_0. and your post-upgrade backup Post-upgrade backup, MYSQL_8_0 from MYSQL_5_7.

As with other on-demand backups, upgrade backups persist until you delete them or delete the instance. If you have PITR enabled, you can't delete your upgrade backups while they're in your retention window. If you need to delete your upgrade backups, you'll need to disable PITR or wait until your upgrade backups are no longer in your retention window.

Complete the major version upgrade

After upgrading your primary instance, perform acceptance tests to ensure that the upgraded system performs as expected.

Troubleshoot a major version upgrade

Cloud SQL returns an error message if you attempt an invalid upgrade command, for example, if your instance contains invalid database flags for the new version.

If your upgrade request fails, check the syntax of your upgrade request. If the request has a valid structure, try looking into the following suggestions.

View upgrade logs

If any issues occur with a valid upgrade request, Cloud SQL publishes error logs to projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fmysql.err. Each log entry contains a label with the instance identifier to help you identify the instance with the upgrade error. Look for such upgrade errors and resolve them.

To view error logs, follow these steps:

  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. In the Operations and logs pane of the instance Overview page, click the View MySQL error logs link.

    The Logs Explorer page opens.

  4. View logs as follows:

    • To list all error logs in a project, select the log name in the Log name log filter.

      For more information on query filters, see Advanced queries.

    • To filter the upgrade error logs for a single instance, enter the following query in the Search all fields box, after replacing DATABASE_ID with the project ID followed by the instance name in this format: project_id:instance_name.

      logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fmysql.err"

      For example, to filter the upgrade error logs by an instance named shopping-db running in the project buylots, use the following query filter:

      logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fmysql.err"

Restore to the previous major version

If your upgraded database system doesn't perform as expected, you might need to restore your instance to the previous version. You do so by restoring your pre-upgrade backup to a Cloud SQL recovery instance, which is a new instance running the pre-upgrade version.

To restore to the previous version, perform the following steps:

  1. Identify your pre-upgrade backup.

    See Automatic upgrade backups.

  2. Create a recovery instance.

    Create a new Cloud SQL instance using the major version that Cloud SQL was running when the pre-upgrade backup was made. Set the same flags and instance settings that the original instance uses.

  3. Restore your pre-upgrade backup.

    Restore your pre-upgrade backup to the recovery instance. This might take several minutes to complete.

  4. Add your read replicas.

    If you were using read replicas, add them individually.

  5. Connect your application.

    Having recovered your database system, update your application with details about the recovery instance and its read replicas. You can resume serving traffic on the pre-upgrade version of your database.


The following questions might come up when upgrading the database major version.

Is my instance unavailable during an upgrade?
Yes. Your instance stays unavailable for a period of time for Cloud SQL to perform the upgrade.
How long does an upgrade take?
Upgrading a single instance typically takes less than 10 minutes. Your upgrade time might be longer if your instance hosts too many databases or tables, your databases are very large, or your instance configuration uses a small number of vCPUs or memory. If you have multiple instances that need to be upgraded, your total upgrade time increases proportionately.
Can I monitor each step in my upgrade process?
While Cloud SQL allows you to monitor whether an upgrade operation is still in progress, you are unable to track the individual steps in each upgrade.
Can I cancel my upgrade after I've started it?
No, you can't cancel an upgrade once it has started. If your upgrade fails, Cloud SQL automatically recovers your instance on the previous version.
What happens to my settings during an upgrade?
When you perform an in-place major version upgrade, Cloud SQL retains your database settings, including your instance name, IP address, flag values, and user data. If a certain flag or a flag value is no longer supported in your target version, Cloud SQL automatically removes the flag during the upgrade.

What's next