How to view and upgrade the version of a PolarDB cluster - PolarDB

PolarDB clusters use a three-layer architecture: the database proxy (PolarProxy), the database kernel engine (DB), and the distributed storage (Store). You can upgrade PolarProxy or the kernel engine independently, or upgrade both together.

Upgrade methods

PolarDB for MySQL supports manual and automatic updates of minor engine versions.

Upgrade method	Description
Manual update	You can select the target version and upgrade time based on your business requirements, and then initiate the upgrade. This topic primarily describes manual upgrades.
Automatic update	The system schedules a minor engine version update task when the upgrade conditions are met. For the rules and configuration procedure, see Automatically upgrade minor engine versions.

Precautions

A version upgrade typically takes no more than 30 minutes. During the upgrade, PolarProxy or the database kernel engine is restarted, which may cause transient connection interruptions. Perform the upgrade during off-peak hours and make sure that your application has an automatic reconnection mechanism.
Note
If you have configured Cloud Monitor to monitor PolarDB clusters, you may receive notifications about cluster access exceptions during the upgrade.
During the upgrade, some change-related features in the PolarDB console are unavailable, such as upgrading or downgrading configurations, adding or deleting nodes, modifying parameters, and restarting nodes. However, query-related features such as performance monitoring are not affected. You cannot downgrade the version after an upgrade.
To prevent prolonged service interruptions during the upgrade switchover, the system checks the status of the primary node before the switchover. If the primary node has large transactions or a significant redo log checkpoint backlog and repeatedly fails the checks within the check window, the upgrade is automatically canceled. The cluster version and runtime state remain unchanged, and you receive a corresponding notification. For the resolution, see Handle failed pre-upgrade checks.

View version information

Log in to the PolarDB console，In the navigation pane on the left, click Clusters. Select the Region where the cluster is deployed, and then click the cluster ID to go to the cluster details page。
In the left-side navigation pane, choose Settings and Management > Version Management.
On the Minor Version Upgrade page, in the Version Information section, view the version information of PolarProxy and the database kernel engine.

Manual upgrade

If the current PolarProxy or database kernel engine version of the cluster is not the latest, you can upgrade it as needed.

Go to the target cluster's Settings and Management > Version Management menu. On the Minor Version Upgrade page, in the Upgrade Version section, select Upgrade PolarDB Database Proxy and Kernel, Upgrade Kernel Only, or Upgrade PolarDB Database Proxy Only as needed.
Note
- If the current PolarProxy or database kernel engine version of the cluster is already the latest, the Upgrade PolarDB Database Proxy and Kernel, Upgrade Kernel Only, and Upgrade PolarDB Database Proxy Only options are grayed out and unavailable.
- If you select Upgrade PolarDB Database Proxy Only, only features related to read/write splitting are upgraded, such as the consistency level (global consistency), transaction splitting, and whether the primary database accepts read requests.
Click Upgrade Now or Upgrade in Maintenance Window. If you select Upgrade in Maintenance Window, you can view the task details or cancel the task on the Scheduled Tasks page. For details, see Scheduled tasks.
Important
- Upgrade PolarDB Database Proxy and Kernel causes transient disconnections of 30 to 90 seconds on both the primary endpoint and the cluster endpoint. Make sure that your application has a reconnection mechanism.
  Note
  Apart from the impact described above, a minor version upgrade does not affect normal cluster use for the rest of the process.
- Upgrade PolarDB Database Proxy Only causes a 30-second transient disconnection of the cluster endpoint and custom endpoints. Connections to the primary endpoint are not affected. Make sure that your application has a reconnection mechanism.
- Upgrade Kernel Only: during the upgrade, a PolarProxy version of 2.4.7 or later on a PolarDB cluster enables Connection Preserving to protect 95% of database connections from interruption.
View the upgrade task:
- In the header of the cluster details page, click the task icon button on the right to view the task progress panel and the upgrade progress.
- Return to Clusters. In the left-side navigation pane, choose Task Management > Task Center, where you can view the task lists for all clusters.

Handle failed pre-upgrade checks

Before the upgrade switchover, the system performs the following two checks on the primary node of the cluster. If the checks repeatedly fail within the check window, the upgrade is automatically canceled. The cluster does not undergo a version change, and its runtime state remains the same as before the upgrade. You can initiate the upgrade again after you resolve the issue.

Check 1: Large transactions on the primary node

The system calculates the total number of rows modified by all active uncommitted transactions on the primary node.

Locate large transactions:

You can connect to the primary node by using a privileged account and run the following statement to check. Querying this view requires the PROCESS privilege. You can also view transactions in session management in DMS or DAS:
```
SELECT SUM(trx_rows_modified) AS sum_trx_rows_modified
FROM information_schema.innodb_trx;
```
A NULL result indicates that no active transactions exist. If the result shows transactions that have modified a large number of rows, run the following statement to locate the specific transactions:
```
SELECT trx_id, trx_state, trx_started, trx_mysql_thread_id,
 trx_rows_modified, LEFT(trx_query, 200) AS trx_query
FROM information_schema.innodb_trx
ORDER BY trx_rows_modified DESC
LIMIT 10;
```

Resolution:

(Recommended. No impact on your workloads.) Wait for the transaction to commit normally, and then retry the upgrade.
If you confirm that the transaction can be discarded, use the KILL command to terminate the session that corresponds to trx_mysql_thread_id.
- Do not use KILL QUERY. It terminates only the current statement. The transaction remains open and is not rolled back, so the check still cannot pass.
- After you run KILL, the transaction enters rollback (trx_state is ROLLING BACK). During this period, the transaction still appears in information_schema.innodb_trx, and the number of modified rows gradually decreases. Wait until it disappears from the query results before you initiate the upgrade again.

Long-term maintenance recommendations:

Split large-scale INSERT ... SELECT, UPDATE, and DELETE operations, as well as data import and archiving jobs, into small batches for submission, and schedule them outside the upgrade window.

Check 2: Redo log checkpoint backlog

The system checks the difference between the redo LSN written on the primary node and the checkpoint LSN. This difference indicates how far checkpoint advancement lags behind writes. If the difference is excessively large, the switchover takes longer to catch up, which prolongs service unavailability.

Query the LSNs:

You can use a privileged account to run the following statement:

SHOW STATUS LIKE '%lsn%';

The difference between Innodb_lsn and Innodb_log_checkpoint_lsn is the current backlog, in bytes.

Resolution:

Pause write-intensive operations, such as large-scale data import, archiving, and DDL, to reduce write pressure.
Run the preceding statement again at intervals and observe whether the difference continues to decrease. Initiate the upgrade again after the difference decreases.

Checklist before retrying the upgrade

The total number of rows modified by active uncommitted transactions on the primary node meets the pre-upgrade check requirement.
information_schema.innodb_trx contains no transaction in the ROLLING BACK state.
Innodb_lsn and Innodb_log_checkpoint_lsn show a stable or decreasing difference.
The upgrade is scheduled outside bulk-operation windows and during off-peak hours.

Related API operations

API	Description
DescribeDBClusterVersion	Queries the kernel version information of a PolarDB cluster.
UpgradeDBClusterVersion	Upgrades the kernel version of a PolarDB cluster.