how to upgrade between polardb for mysql clusters - PolarDB

This topic describes the procedure for upgrading a PolarDB for MySQL cluster.

Pre-checks

Note

If you have completed the upgrade evaluation and no exceptions are found, you can skip this check and proceed to the next step.

Check whether the PolarDB service-linked role is created

Before you perform an upgrade, check whether the PolarDB service-linked role is created and whether you have granted DTS permissions to access cloud resources.

Check whether the service-linked role for PolarDB is created
1. Log on to the Roles page in the Resource Access Management (RAM) console.
2. Check whether a service-linked role named AliyunServiceRoleForPolarDB already exists in the list as shown in the following figure.
  1. If the service-linked role exists in the list, skip this check.
  2. If the service-linked role does not exist in the list, continue this check.
3. In the upper-left corner, click Create Role. On the Create Role page, click Create Service Linked Role in the upper-right corner.
4. On the Create Service Linked Role page, select ApsaraDB for POLARDB from the Select Service drop-down list. Click Create Service Linked Role.
Check whether DTS is authorized to access Alibaba Cloud resources
Only how to check authorization results and fast authorization method are described here. For more information, see Authorize DTS to access Alibaba Cloud resources.
Check authorization results
Log on to the Roles page in the Resource Access Management (RAM) console.
Check whether a service-linked role named AliyunDTSDefaultRole already exists in the list as shown in the following figure.
If the service-linked role does not exist in the list, perform operations in Fast authorization.
If the service-linked role exists in the list, perform the subsequent operations to check its permissions.
Click the AliyunDTSDefaultRole role name and view the details.
If the AliyunDTSDefaultRole role meets all the following requirements, it is properly authorized.
The AliyunDTSRolePolicy policy is displayed on the Permissions tab.
dts.aliyuncs.com is displayed on the Trust Policy tab.
If the AliyunDTSDefaultRole role meets the preceding requirements, it is not authorized. You can delete the AliyunDTSDefaultRole role and perform authorization again.
Fast authorization
Log on to the Roles page in the Resource Access Management (RAM) console. In the Authorize Access to Cloud Resources diaglog box, click Authorize.
Note
If the "Cloud resource access authorization successful" mesage is displayed, it is authorized.
For more information about authorzation, see Authorize DTS to access Alibaba Cloud resources.

Remove extra system accounts from the source PolarDB for MySQL cluster

To prevent the system account of the destination PolarDB for MySQL cluster from being overwritten during migration, ensure that the root and aliyun_root accounts do not exist in the source PolarDB for MySQL cluster at the same time. Before you start the migration process, you must remove extra system accounts from the source PolarDB for MySQL cluster.

The following table lists the correct system account name for each version of PolarDB for MySQL.

Database engine version	Correct system account name
MySQL 5.6	root
MySQL 5.7	aliyun_root
MySQL 8.0	root

All system accounts other than the one specified for your cluster version in the preceding table must be removed. For example, the correct system account for a PolarDB MySQL 5.7 cluster is aliyun_root. If you manually created a root account in the console, you must delete it. Before you delete the root account, ensure that it is not used by your application.

Note

These system accounts may have been created manually or created automatically by the system and retained after a version upgrade. In some scenarios, specific accounts may not be visible in the console.

Example

The following example shows how to remove extra system accounts from a PolarDB MySQL 5.6 cluster:

Use a privileged account to connect to a database.

Find all root and aliyun_root system accounts.

SELECT * FROM mysql.user WHERE `user` IN ('root', 'aliyun_root');

Remove the extra system accounts. The correct system account for a PolarDB MySQL 5.6 cluster is root. Therefore, you must remove the aliyun_root account.
```
DELETE FROM mysql.user WHERE `user` = 'aliyun_root' LIMIT n;
```

(Optional) Perform intelligent stress testing

Before you perform a major version upgrade, you can use the intelligent stress testing feature to simulate your application traffic on a PolarDB cluster that runs the destination version. This helps you achieve the following goals:

Check whether your cluster specifications need to be scaled out to handle application traffic peaks.
Analyze the differences in SQL template execution performance between the source and destination PolarDB clusters.

For more information about how to perform an intelligent stress testing task, see Traffic playback and stress testing.

Step 1: Upgrade and migrate from PolarDB

In this step, you create a new cluster that contains the same data as your source PolarDB for MySQL cluster. The incremental data from the source PolarDB for MySQL cluster is then synchronized to the new cluster in real time.

Note

Before you start the migration, we recommend that you complete the upgrade evaluation.
If you use DTS to migrate data, DTS uses the read and write resources of the source and destination databases during the initial full data synchronization. This may increase the load on the database servers. You can adjust the migration rate as needed.

Log on to the PolarDB console.
Go to the cluster purchase page. You can go to the purchase page in one of the following ways:
- Click Create New Cluster.
- Click the ID of the cluster that you want to upgrade. In the navigation pane on the left, choose Configuration and Management > Version Management. On the Major Version Upgrade tab, click Upgrade by Migration.
Set Billing Method to Subscription, Pay-As-You-Go, or Serverless.
- Subscription: You must pay for compute nodes when you create the cluster. Storage is billed based on the actual data volume per hour, and fees are deducted from your account hourly.
- Pay-As-You-Go: You do not need to pay in advance. Compute nodes and storage space are billed based on the actual data volume per hour, and fees are deducted from your account hourly.
- Serverless: You do not need to pay in advance. Resources such as compute nodes, storage space, and database proxies dynamically and elastically scale based on the actual requirements during cluster use. You are charged based on the actual usage of the scaled resources.

Set the following parameters as needed.

Note

For more information about the parameters that are not described in the following table, see Purchase a cluster.

Parameter	Description
Creation Method	Select Upgrade/Migrate from PolarDB.
Region	Select the region where the source PolarDB for MySQL cluster is located.
Source PolarDB Version	The version of the source PolarDB for MySQL cluster. You can select 5.6, 5.7, or 8.0.
Source PolarDB Cluster	Select the source PolarDB for MySQL cluster.
Database Engine	The database engine version of the destination cluster. Note When you upgrade the version, you can select the same version as the source cluster or a different version. When you upgrade the architecture, you must select MySQL 8.0.
Product Version	The product version is the same as that of the source cluster. You do not need to select a version.
Series	The series of the destination cluster. Note When you upgrade the version, select Cluster Edition (Recommended). When you upgrade the architecture, select Multi-master Cluster (Limitless).
CPU Architecture	The CPU architecture is the same as that of the source cluster. You do not need to select an architecture.
Node Count	The number of nodes is the same as that of the source cluster. You do not need to select a number.
Current Selected Specifications	The node specifications of the destination cluster.
Database Proxy Type	The database proxy specifications are the same as those of the source cluster. You do not need to select specifications.

In the upper-right corner, check the cluster configuration information. Set Subscription Duration (for Subscription clusters), Quantity, and Auto-renewal.
Read and select the Terms of Service. Click Buy Now.
On the Payment page, confirm the order information and payment method, and then click Order.
Note
- After the payment is successful, wait 10 to 15 minutes for the cluster to be created. You can then view the new cluster on the Clusters page.
- If the status of a node in the cluster is Creating, the cluster is still being created and is unavailable. The cluster can be used only when its status changes to Running.
- Ensure that you have selected the correct region. Otherwise, you cannot view the cluster that you created.
After the cluster is created, click the cluster ID to go to the Basic Information page of the cluster.
In the PolarDB Upgrade Feature section of the Basic Information page, ensure that the Replication Delay of the destination PolarDB cluster is less than 60 seconds before you proceed.
Note
- You cannot perform a one-click upgrade on a cluster that has an existing DTS two-way synchronization task. Data inconsistency may occur.
- After the cluster is created, DTS starts to synchronize data from the source PolarDB cluster. You must complete the upgrade within 30 days. After 30 days, the upgrade feature is automatically disabled.
- You can click Cancel Upgrade in this section. For more information about the impact of canceling an upgrade, see the FAQ.
- If the status is Precheck Failed, resolve the issue based on the error message.
  For example, if a trigger is created in the source PolarDB cluster, the precheck fails and an error message indicates that a trigger exists in the PolarDB cluster. You must delete the trigger from the PolarDB cluster and click Continue Upgrade. Alternatively, you can click Cancel Upgrade and manually create a migration task in the DTS console. For more information, see Configure a synchronization or migration job when the source database contains triggers.
- During an architecture upgrade, the default write endpoint is the RW node with MasterID=1. To ensure that the DTS data synchronization task runs as expected, always write to this RW node before the upgrade is complete.

(Optional) Step 2: Add endpoints

Major version upgrades of PolarDB support endpoint switchover. This feature lets you retain the original database endpoint and switch to the new PolarDB cluster without modifying the connection configurations in your application. Note that endpoints can be switched over only if they exist on both the source PolarDB cluster and the destination PolarDB cluster. By default, only a private primary endpoint and a private cluster endpoint are created for the destination instance. If the source instance has more than two endpoints, you must create the corresponding endpoints on the destination instance before the switchover. Otherwise, those additional endpoints will not be switched. For more information about how to create an endpoint for a PolarDB cluster, see Manage endpoints.

Note

You can add endpoints only after the destination cluster is in the Running state. You can also configure endpoint properties, configure cluster parameters, and add read-only nodes as needed.
Before you use the endpoint switchover feature to switch private endpoints, ensure that the source PolarDB cluster and the destination PolarDB cluster are in the same VPC. Otherwise, the original service cannot connect after the switchover.

Step 3: Switch over services

You can switch over services when the replication delay of the destination PolarDB cluster is less than 60 seconds.

Log on to the PolarDB console.
Find the destination cluster and click the cluster ID.
In the PolarDB Upgrade Feature section of the Basic Information page, click Upgrade Switchover.
Note
- In most cases, the switchover is completed within 5 minutes.
- This operation switches the read/write status of the source PolarDB cluster and the destination PolarDB cluster. The source PolarDB cluster is changed to read-only, and the destination PolarDB cluster is changed to read/write. At the same time, DTS changes the data replication direction. Incremental data is synchronized from the destination PolarDB cluster to the source PolarDB cluster.
In the Upgrade Switchover dialog box, select Switch with Endpoints (Application Connection Configuration Unchanged) or Switch without Endpoints (Application Needs to Be Changed to the New PolarDB Connection Configuration).
- If you select Switch with Endpoints (Application Connection Configuration Unchanged), perform the following steps:
  1. Select Switch with Endpoints (Application Connection Configuration Unchanged). The system automatically switches the endpoints on the source PolarDB cluster and the destination PolarDB cluster. You do not need to modify any configurations on the application side to automatically connect to the destination PolarDB cluster.
    Important
    Before you select Switch with Endpoints (Application Connection Configuration Unchanged), read Notes on endpoint switchover.
    If the PolarDB cluster that you want to upgrade is the source or destination cluster of an existing Data Transmission Service (DTS) task, you must change the source or destination cluster of the DTS task to the upgraded PolarDB cluster after the upgrade. These tasks include data synchronization tasks, data migration tasks, and change tracking tasks. For more information, see Modify the objects of a DTS task.
  2. Click OK.
- If you select Switch without Endpoints (Application Needs to Be Changed to the New PolarDB Connection Configuration), perform the following steps:
  1. Select Switch without Endpoints (Application Needs to Be Changed to the New PolarDB Connection Configuration).
  2. Click OK.
  3. Refresh the page. When the Read/Write Status of the destination PolarDB cluster changes to Read/Write, modify the database endpoint in your application as soon as possible.

Note

After the upgrade switchover is complete, if you find data exceptions or other issues, you can perform a rollback operation to quickly restore the cluster to its state before the upgrade. You can also choose to roll back the upgrade.
After the architecture upgrade and switchover are complete, do not modify the write endpoint of the destination Multi-master Cluster (Limitless) Edition cluster to prevent DTS data synchronization task exceptions.

(Optional) Step 4: Switch over DTS tasks for the source instance

Note

If the source instance has an associated DTS link that is not for a one-click migration, you can use this feature to modify or replace the source or destination database instance of the DTS synchronization or migration task to smoothly switch the associated services. For more information about the principles and notes, see Modify the source or destination database instance of a DTS task.

Go to the PolarDB console.
Find the destination cluster and click the cluster ID.
In the PolarDB Migration Feature section of the Basic Information page, click Source Instance DTS Task Switchover.
In the Switch Business DTS Database dialog box, select Source Instance DTS Task (Forward Switchover) or Destination Instance DTS Task (Switchover Rollback).
Important
Before the switchover, check the DTS status of the data synchronization between the source and destination instances. For more information about how to query the DTS status, see Query DTS status.
Source Instance DTS Task (Forward Switchover)
If you select Source Instance DTS Task (Forward Switchover), perform the following steps:
1. Select the DTS task for which you want to switch the database instance.
2. Click Submit Forward Switchover.
Destination Instance DTS Task (Switchover Rollback)
If you select Destination Instance DTS Task (Switchover Rollback), perform the following steps:
1. Select the DTS task for which you want to switch the database instance.
2. Click Submit Switchover Rollback.

Note

The Source Instance DTS Task (Forward Switchover) feature switches the DTS task from the source instance to the destination instance after the migration switchover. After the migration switchover, you must complete the DTS task operations that were performed before the migration.
The Switchover Rollback feature is used to switch a DTS task from the destination instance back to the source instance. This operation must be performed before you cancel the migration.

Step 5: Complete the upgrade

After you complete Step 1: Upgrade and migrate from PolarDB, you must complete the upgrade within 30 days.

Important

Before you click Complete Upgrade, ensure that the data has been migrated and that you no longer need the data synchronization feature.
This operation interrupts the data synchronization task between the source PolarDB cluster and the destination PolarDB cluster. The upgrade rollback feature is then no longer available. We recommend that you use the destination PolarDB cluster for a period of time and complete the upgrade only after you confirm that it runs as expected.

Log on to the PolarDB console.
Find the destination cluster and click the cluster ID.
In the PolarDB Upgrade Feature section of the Basic Information page, click Complete Upgrade.
In the Complete Upgrade dialog box, you can select whether to disable binary logging for the PolarDB cluster and click OK.
Note
- After you click OK, the system interrupts the synchronization task within 2 minutes. The upgrade status changes to Disabling Synchronization.
- If you choose to disable binary logging, the PolarDB cluster automatically restarts for the new configuration to take effect.
- If you no longer require the source PolarDB cluster, you can release the source PolarDB cluster. For information about how to release a cluster, see Release a cluster.
- If you are performing an architecture upgrade, the write endpoint of the destination cluster is restored to its initial state after you click OK in the Complete Upgrade dialog box. The database randomly designates an RW node as the write endpoint.

(Optional) View the details of a data synchronization task

If an upgrade error or another exception occurs during the version upgrade, you can go to the details page of the corresponding DTS data synchronization task to view detailed information.

Log on to the PolarDB console.
Find the destination cluster and click the cluster ID.
In the PolarDB Upgrade Feature section of the Basic Information page, click the name of the DTS Data Synchronization Task to go to the data synchronization task list in the DTS console.
In the data synchronization task list, find the data synchronization task. You can then view the task details and task logs.
During the upgrade, if your requirements change, for example, a new database is added to the source PolarDB cluster and you need to include the new database as a synchronization object, you can click Modify Synchronization Object to reconfigure the task.

(Optional) Roll back the upgrade

If you find data exceptions or other issues before you complete the upgrade, you can roll back the upgrade to quickly restore the cluster to its state before the upgrade. The source PolarDB cluster becomes read/write, the destination PolarDB cluster becomes read-only, and data from the source PolarDB cluster is synchronized to the destination PolarDB cluster. After the upgrade is rolled back, if you want to proceed with the major version upgrade, you can start from Step 3: Switch over services.

Log on to the PolarDB console.
Find the destination cluster and click the cluster ID.
In the PolarDB Upgrade Feature section of the Basic Information page, click Upgrade Rollback.
In the Start Failback dialog box, select Failback with Endpoints (Application Connection Configuration Unchanged) or Failback without Endpoints (Application Needs to Be Changed to the Source Cluster Connection Configuration).
- If you select Failback with Endpoints (Application Connection Configuration Unchanged), perform the following steps:
  1. Select Failback with Endpoints (Application Connection Configuration Unchanged). The system automatically switches the endpoints on the source PolarDB cluster and the destination PolarDB cluster. You do not need to modify any configurations on the application side to automatically fail back to the source PolarDB cluster.
  2. Click OK.
    At this time, the source PolarDB cluster is read/write, the destination PolarDB cluster is read-only, and data from the source PolarDB cluster is synchronized to the destination PolarDB cluster.
    Note
    When you roll back an architecture upgrade, you can select the rollback address as needed.
- If you select Failback without Endpoints (Application Needs to Be Changed to the Source Cluster Connection Configuration), perform the following steps:
  1. Select Failback without Endpoints (Application Needs to Be Changed to the Source Cluster Connection Configuration). After the rollback is complete, you must modify the database connection pool address on the application side as soon as possible.
  2. Click OK. At this time, the source PolarDB cluster is read/write, the destination PolarDB cluster is read-only, and data from the source PolarDB cluster is synchronized to the destination PolarDB cluster.
  3. Refresh the page. When the status of the source PolarDB cluster changes to read/write, modify the database endpoint in your application to the endpoint of the source PolarDB cluster as soon as possible.

(Optional) Cancel the upgrade

Log on to the PolarDB console.
Find the destination cluster and click the cluster ID.
In the PolarDB Upgrade Feature section of the Basic Information page, click Cancel Upgrade.
In the Cancel Upgrade dialog box, click OK.

FAQ

If triggers are created in the source PolarDB cluster, will they affect a major version upgrade task?

Yes. If triggers have been created in the source PolarDB cluster, the task status changes to Precheck Failed in Step 1: Upgrade and migrate from PolarDB. You must delete the triggers before you perform the major version upgrade. After the upgrade is complete, you can manually create the triggers in the destination PolarDB cluster.

How do I query the triggers in the source PolarDB cluster?

You can query the information_schema.triggers table to view the triggers in the source PolarDB cluster.

SELECT * FROM information_schema.triggers;

How do I delete the triggers in the source PolarDB cluster?

You can run the following SQL statement to generate the SQL statements that are used to delete the triggers.

Important

Before you delete the triggers, carefully check their potential impact on your services and back up the triggers. After the major version upgrade is complete, you must manually create the corresponding triggers in the destination PolarDB cluster.

SELECT TRIGGER_SCHEMA,concat('DROP TRIGGER ',TRIGGER_SCHEMA,'.',TRIGGER_NAME,';') FROM information_schema.triggers;

The following sample output is returned. You can copy and run the following SQL statements to delete the corresponding triggers. In the statements, TRIGGER_SCHEMA is the name of the database to which the trigger belongs.

+----------------+-------------------------------------------------------------+
| TRIGGER_SCHEMA | concat('DROP TRIGGER ',TRIGGER_SCHEMA,'.',TRIGGER_NAME,';') |
+----------------+-------------------------------------------------------------+
| test_triggers  | DROP TRIGGER test_triggers.xxx_insert;                      |
| test_triggers  | DROP TRIGGER test_triggers.xxx_update;                      |
| test_triggers  | DROP TRIGGER test_triggers.xxx_delete;                      |
+----------------+-------------------------------------------------------------+

Pre-checks

Check whether the PolarDB service-linked role is created

Check authorization results

Fast authorization

Remove extra system accounts from the source PolarDB for MySQL cluster

(Optional) Perform intelligent stress testing

Step 1: Upgrade and migrate from PolarDB

(Optional) Step 2: Add endpoints

Step 3: Switch over services

(Optional) Step 4: Switch over DTS tasks for the source instance

Source Instance DTS Task (Forward Switchover)

Destination Instance DTS Task (Switchover Rollback)

Step 5: Complete the upgrade

(Optional) View the details of a data synchronization task

(Optional) Roll back the upgrade

(Optional) Cancel the upgrade

FAQ