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

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. We recommend that you perform the upgrade during off-peak hours and ensure that your application has an automatic reconnection mechanism.

Note
If you have configured Cloud Monitor to monitor your PolarDB cluster, 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 configuration upgrade/downgrade, adding/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 primary node status before the switchover. If the primary node has large transactions or a significant redo log checkpoint backlog and repeatedly fails the checks during the check window, the upgrade is automatically canceled. The cluster version and runtime state remain unchanged, and you will receive a corresponding notification. For troubleshooting, 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, view the version information of PolarProxy and the database kernel engine in the Version Information section.

Upgrade the version

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

Go to the Settings and Management > Version Management menu for the target cluster. On the Minor Version Upgrade page, in the Upgrade Version section, you can 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 is already the latest, the Upgrade PolarDB Database Proxy and Kernel, Upgrade Kernel Only, and Upgrade PolarDB Database Proxy Only options are grayed out.
- If you select Upgrade PolarDB Database Proxy Only, only the features related to read/write splitting are upgraded, such as 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 more information, see Scheduled tasks.
Important
- During Upgrade PolarDB Database Proxy and Kernel, both the primary endpoint and the cluster endpoint experience 30 to 90 seconds of transient disconnections. Make sure your application has a reconnection mechanism.
  
  Note
  Apart from the impact described above, the minor version upgrade does not affect normal cluster usage during the rest of the process.
- During Upgrade PolarDB Database Proxy Only, the cluster endpoint and custom endpoints experience 30 seconds of transient disconnections. The primary endpoint is not affected. Make sure your application has a reconnection mechanism.
- During Upgrade Kernel Only, PolarDB clusters with PolarProxy 2.4.7 or later can use Connection Preserving to protect 95% of database connections from being interrupted.
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 list for all clusters.

Handle failed pre-upgrade checks

Before an upgrade switchover, the system performs the following two checks on the primary node. If either check repeatedly fails during 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 resolving 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 the rollback state (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 result before initiating 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 latest written redo LSN and the checkpoint LSN on the primary node. This difference indicates how far the checkpoint lags behind redo 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 bulk data import, archiving, and DDL operations to reduce write pressure.
Run the statement again after an interval and check 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.
No transaction in information_schema.innodb_trx is in the ROLLING BACK state.
The difference between Innodb_lsn and Innodb_log_checkpoint_lsn is stable or decreasing.
The upgrade is scheduled outside bulk-operation windows and during off-peak hours.

Related API operations

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