Oracle Cloud Infrastructure Documentation

DB System Upgrades

MySQL HeatWave Service supports automatic and manual upgrades.

  • Automatic upgrades:
    • Updates within the same version, such as 8.0.33-u1, are applied automatically during the maintenance window that you define on the DB system. The update versions contain critical patches such as security and stability fixes.
    • A deprecated version becomes unavailable about three months after the deprecation date. See MySQL Versions Deprecation and Removal Policy in MySQL HeatWave Service. Any DB system that is still running an unavailable version will be upgraded automatically in its next maintenance window, according to the maintenance policy defined on the DB System.
    • For an Always Free DB system, the maintenance process will always upgrade the database version to the highest version available.
  • Manual upgrades: You can manually upgrade the version. See:
    Note

    It is recommended to perform a full backup of the DB system before upgrading. See Creating a Manual Backup.

Manually Upgrading a Standalone DB System

Use the Console or CLI to manually upgrade a standalone DB system to a higher version. You can upgrade to the same version (to get the latest security and critical fixes), but you cannot downgrade to an earlier version.

Note

If you want to perform a major version upgrade such as MySQL 8.0 to MySQL 8.4, you should check the changes before upgrading. See Major Version Upgrade.

Using the Console

Use the Console to manually upgrade the standalone DB system.

This task requires the following:
  • A running standalone DB system.
Do the following to upgrade the DB system:
  1. On the DB systems list page, find the DB systems that you want to work with. If you need help finding the list page or the DB system, see Listing DB Systems - Using the Console.
  2. Select the Details tab.
  3. In the Database version field, click Edit.
    The Edit database version pane appears.
  4. From the Database version list, select the required version.
    Note

    You can select the same version to get the latest service updates if the version is still available in the service.
  5. Click Update.
The DB system enters the UPDATING state while it is being upgraded.

Using the CLI

Use the command-line interface to manually upgrade the standalone DB system.

This task requires the following:
Do the following to upgrade the DB system:
  1. To retrieve the list of available versions, use the version list command:
    oci mysql version list --compartment-id <CompartmentOCID>
    You get a response similar to the following:
    {
  "data": [
    {
      "version-family": "8.4",
      "versions": [
        {
          "description": "8.4.6",
          "version": "8.4.6"
        },
        {
          "description": "8.4.7",
          "version": "8.4.7"
    }
  ]
}
  2. Confirm the version of the DB system. See Retrieving the Version of a MySQL Server.
  3. Upgrade the version from a lower version to a higher version such as 8.4.7 to 8.4.8, or to the same version, such as 8.4.7 to 8.4.7 to get the latest service updates:
    oci mysql db-system update 
             --db-system-id <DBSystemOCID> 
             --mysql-version <TargetMySQLVersion>
After you run the CLI command, the status of the DB system changes to UPDATING and subsequently the version changes to the specified target MySQL version.

Manually Upgrading a High Availability DB System

When you upgrade a high availability DB system, the read replicas are upgraded first, followed by the secondary nodes, leaving the primary node for last. Up to this point, no downtime is expected for the DB system primary endpoint. When the upgrade of the primary node begins, existing connections to the primary are closed and no new connections are permitted. The primary node is removed from the group and one of the already-upgraded secondary nodes is promoted to primary. This controlled failover is expected to cause a brief period of downtime until connections are accepted again on the newly promoted primary.

You can choose to upgrade all the instances at once. Or you can perform a controlled upgrade of the DB system in two separate phases, which lets you decide when the downtime of the primary endpoint of the DB system occurs. However, a controlled upgrade can be performed on a DB system in read-write mode only. To perform a controlled upgrade, you must first upgrade the secondary nodes and read replicas and then upgrade the primary node to the same target MySQL version. If you do not upgrade the primary node after upgrading the secondary nodes and read replicas, the primary node is automatically upgraded during the next scheduled maintenance window. An upgrade is considered complete only when all MySQL instances in the high availability DB system have been upgraded to the same version.

While a controlled upgrade is incomplete or in progress:

  • If a new read replica is created or if security fixes and patches need to be applied to the existing secondary nodes or read replicas, the read replicas and secondary nodes must be upgraded again before upgrading the primary node.
  • You can initiate another controlled upgrade to the same or higher version.
  • You cannot switch the DB system from read-write to read-only mode.
Use the Console or CLI to manually upgrade a DB system to a higher version. You can upgrade to the same version (to get the latest security and critical fixes), but you cannot downgrade to an earlier version.
Note

If you want to perform a major version upgrade such as MySQL 8.4 to MySQL 9.6, you should check the changes before upgrading. See Major Version Upgrade.

Using the Console

Use the Console to manually upgrade the high availability DB system.

This task requires the following:
  • A running high availability DB system.
Do the following to upgrade the DB system:
  1. On the DB systems list page, find the DB systems that you want to work with. If you need help finding the list page or the DB system, see Listing DB Systems - Using the Console.
  2. Select the Details tab.
  3. In the Database version field, click Edit.
    The Edit database version pane appears.
  4. From the Controlled update target list, select one of the following options:
    • Update all instances at once: to upgrade all instances. If you have not already performed a controlled upgrade of the secondary nodes and read replicas, this is selected by default.
    • Update all instances but the primary: to upgrade all instances except the primary node, which includes the secondary nodes and read replicas, if any.
    • Update the primary only: to upgrade the primary node only. If you have already performed a controlled upgrade of the secondary nodes and read replicas, this is selected by default.
      Note

      This option is enabled only after you have completed a controlled upgrade of the secondary nodes and read replicas.
  5. From the Database version list, select the required version.
    Note

    You can select the same version to get the latest service updates if the version is still available in the service.
  6. Click Update.
The DB system enters the UPDATING state while it is being upgraded.

Using the CLI

Use the command-line interface to manually upgrade the high availability DB system.

This task requires the following:
Do the following to upgrade the DB system:
  1. To retrieve the list of available versions, use the version list command:
    oci mysql version list --compartment-id <CompartmentOCID>
    You get a response similar to the following:
    {
  "data": [
    {
      "version-family": "8.4",
      "versions": [
        {
          "description": "8.4.6",
          "version": "8.4.6"
        },
        {
          "description": "8.4.7",
          "version": "8.4.7"
    }
  ]
}
  2. Confirm the version of the DB system. See Retrieving the Version of a MySQL Server.
  3. Upgrade the version from a lower version to a higher version such as 8.4.7 to 8.4.8, or to the same version, such as 8.4.7 to 8.4.7 to get the latest service updates:
    oci mysql db-system update 
             --db-system-id <DBSystemOCID> 
             --mysql-version <TargetMySQLVersion>

    Alternatively, to specify the upgrade target instances for a controlled upgrade, use the following command: 

    oci mysql db-system controlled-update  
             --db-system-id=<DBSystemOCID> 
             --target-mysql-version=<TargetMySQLVersion>  
             --target-db-instances=<TargetDBInstances>
After you run the CLI command, the status of the DB system changes to UPDATING and subsequently the version changes to the specified target MySQL version.