MySQL version upgrade
You can upgrade a Managed Service for MySQL cluster to any supported minor or major version.
In single-host clusters, the only master host is brought out of its running state for upgrades. Unlike multi-host clusters, these clusters are not available for reads and writes during an upgrade.
In multi-host clusters, upgrades follow the procedure below:
- The replicas are withdrawn from service one by one for an upgrade. Their queue positions are random. Following an upgrade, the replicas are put back online.
- A master host is closed for writes. A new master host is selected from among the replicas and opened for writes. As a result, the cluster is updated with minimal downtime.
- The original master host is shut down, upgraded, and resumes its operation as a replica. It does not take back its role as a master.
To learn more about updates within one version and host maintenance, see Maintenance in Managed Service for MySQL.
Alert
- Once your DBMS is upgraded, you cannot roll a cluster back to the previous version.
- The success of a MySQL version upgrade depends on multiple factors, including cluster settings and data stored in databases. We recommend that you first upgrade a test cluster that uses the same data and settings.
- Upgrade your cluster when it is less loaded.
Before updating the version
Make sure the update does not affect your applications:
- See the MySQL changelog
to check how updates might affect your applications. - Try updating the version on a test cluster. You can deploy it from a backup of the main cluster. Use the
PRESTABLE
environment for the test cluster. - Create a backup of the main cluster before updating the version.
- Since a cluster of three or more hosts is fault-tolerant, make sure the primary and test clusters have at least two replica hosts and a single master host. Add hosts as needed.
Upgrading a cluster
- Go to the folder page and select Managed Service for MySQL.
- Select the appropriate cluster from the list and click
Edit cluster. - In the Version field, select a new version number.
- Click Save changes.
Once the update is launched, the cluster status will change to Updating. Wait for the operation to complete and then check the cluster version.
The upgrade time depends on multiple factors, e.g., the amount of data or the number of databases in the cluster. The upgrade usually takes several minutes, and 10 minutes or more for large databases.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
To update the MySQL version:
-
Get a list of your MySQL clusters using this command:
yc managed-mysql cluster list
-
Get information about a cluster and check the MySQL version in the
config.version
parameter:yc managed-mysql cluster get <cluster_name_or_ID>
-
Start the MySQL upgrade:
yc managed-mysql cluster update <cluster_name_or_ID> \ --mysql-version <new_version_number>
The upgrade time depends on multiple factors, e.g., the amount of data or the number of databases in the cluster. The upgrade usually takes several minutes, and 10 minutes or more for large databases.
-
Open the current Terraform configuration file with an infrastructure plan.
For more information about creating this file, see Creating a MySQL cluster.
-
Add the
version
field to theyandex_mdb_mysql_cluster
resource or change the field value if it already exists:resource "yandex_mdb_mysql_cluster" "<cluster_name>" { ... version = "<MySQL_version>" ... }
-
Make sure the settings are correct.
-
Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.
-
Run the command:
terraform validate
If there are errors in the configuration files, Terraform will point to them.
-
-
Confirm updating the resources.
-
Run the command to view planned changes:
terraform plan
If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
-
If you are happy with the planned changes, apply them:
-
Run the command:
terraform apply
-
Confirm the update of resources.
-
Wait for the operation to complete.
-
-
For more information, see the Terraform provider documentation
Time limits
A Terraform provider sets the timeout for Managed Service for MySQL cluster operations:
- Creating a cluster, including by restoring one from a backup: 15 minutes.
- Editing a cluster, including the MySQL version update: 60 minutes.
- Deleting a cluster: 15 minutes.
Operations exceeding the set timeout are interrupted.
Add the timeouts
block to the cluster description, for example:
resource "yandex_mdb_mysql_cluster" "<cluster_name>" {
...
timeouts {
create = "1h30m" # 1 hour 30 minutes
update = "2h" # 2 hours
delete = "30m" # 30 minutes
}
}
To upgrade a cluster to a specific MySQL version, use the update REST API method for the Cluster resource or the ClusterService/Update gRPC API call and provide the following in the request:
- Cluster ID in the
clusterID
parameter. To find out the cluster ID, get a list of clusters in the folder. - MySQL version number in the
configSpec.version
parameter. - List of cluster configuration fields to update in the
UpdateMask
parameter.
Warning
This API method overrides all parameters of the object being modified that were not explicitly passed in the request to the default values. To avoid this, list the settings you want to change in the updateMask
parameter (one line separated by commas).
The upgrade time depends on multiple factors, e.g., the amount of data or the number of databases in the cluster. The upgrade usually takes several minutes, and 10 minutes or more for large databases.
Examples
Let's assume you need to upgrade your cluster from version 5.7 to 8.0.
-
To get a list of clusters and find out their IDs and names, run this command:
yc managed-mysql cluster list
Result example:
+----------------------+------------+---------------------+--------+---------+ | ID | NAME | CREATED AT | HEALTH | STATUS | +----------------------+------------+---------------------+--------+---------+ | c9q8p8j2gaih******** | mysql406 | 2021-10-23 12:44:17 | ALIVE | RUNNING | +----------------------+------------+---------------------+--------+---------+
-
To get information about a cluster named
mysql406
, run the this command:yc managed-mysql cluster get mysql406
Result example:
id: c9q8p8j2gaih******** ... config: version: "5.7" ...
-
To upgrade the
mysql406
cluster to version 8.0, run this command:yc managed-mysql cluster update mysql406 --mysql-version 8.0
-
Open the current Terraform configuration file with an infrastructure plan.
-
Set the
version
field value to8.0
in theyandex_mdb_mysql_cluster
resource.resource "yandex_mdb_mysql_cluster" "<cluster_name>" { ... version = "8.0" ... }
-
Make sure the settings are correct.
-
Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.
-
Run the command:
terraform validate
If there are errors in the configuration files, Terraform will point to them.
-
-
Confirm updating the resources.
-
Run the command to view planned changes:
terraform plan
If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
-
If you are happy with the planned changes, apply them:
-
Run the command:
terraform apply
-
Confirm the update of resources.
-
Wait for the operation to complete.
-
-