Upgrade Percona XtraDB Cluster¶

You must make backups before attempting an upgrade.

This guide explains how to upgrade a Percona XtraDB Cluster to version 8.4 without causing downtime. This process is called a “rolling upgrade,” which means you can upgrade the cluster one node at a time without shutting down the whole cluster. Keep in mind that rolling upgrades to 8.4 are only supported if your current version is 8.0 or newer. Be sure you are running on the latest 8.0 version before you upgrade to 8.4.

Upgrading to Percona Server 8.4 is similar to upgrading between minor versions of 8.0, like from 8.0.x to 8.0.y. There are a few specific details to keep in mind for 8.4, but the overall process isn’t very different. We also recommend checking out the Percona Server upgrade documentation for more information: Percona Server for MySQL 8.4 Upgrade Guide.

Upgrade from 5.7¶

If you are using Percona XtraDB Cluster 5.7, it’s best to shut down all the nodes, remove the cluster, and create it again from scratch. Another option is to do a rolling upgrade from PXC 5.7 to 8.0 first. Once that’s done, you can follow the current steps to upgrade from 8.0 to 8.4.

Important changes in Percona XtraDB Cluster 8.4¶

Keyring Plugin vs. Keyring Component¶

Starting with version 8.4, Percona XtraDB Cluster (PXC) no longer supports the keyring plugin. Instead, it uses the keyring component.

Requirement	Details
In-Place Upgrade	During an in-place upgrade, you need to update your `my.cnf` configuration. Replace the keyring plugin settings with the keyring component configuration. This includes updating the manifest and the component configuration file. Learn more about installing the keyring component here.
Rolling Upgrade	When performing a rolling upgrade, the donor node (running an older version) can still use the keyring plugin, while the 8.4 node uses the keyring component. Since both use the keyring for encryption, they remain compatible and work together seamlessly.
Other Requirements	All other requirements, such as ensuring the SST (State Snapshot Transfer) channel is SSL-encrypted when using the keyring plugin or component, remain the same as in version 8.0.

caching_sha2_password is the default authentication plugin¶

In Percona XtraDB Cluster 8.4, the default authentication plugin is caching_sha2_password. In ProxySQL 2.6.2 or later, use the caching_sha2_password authentication method.

ProxySQL 2.6.2 or later¶

If you are using a version before ProxySQL 2.6.2, the option –syncusers would not work if the Percona XtraDB Cluster user is created using caching_sha2_password. Use the mysql_native_password authentication plugin in these cases. You must load the authentication plugin.

Default Security and Compatibility Settings¶

PXC Strict Mode is enabled by default, which may result in denying any unsupported operations and may halt the server. For more information, see pxc-strict-mode is enabled by default.

pxc-encrypt-cluster-traffic is enabled by default. You need to configure each node accordingly and avoid joining a cluster with unencrypted cluster traffic. For more information, see Traffic encryption is enabled by default.

Do not mix PXC 8.0 nodes with PXC 8.4 nodes¶

In Percona Server for MySQL versions 8.0 and 8.4, both use Galera 4, so there are no issues at the Galera protocol layer that would prevent any node from being a writer in a mixed-version cluster. However, 8.4 introduces changes that might not work on 8.0. If you run these changes on 8.4 and replicate them to 8.0, it could cause node inconsistencies, and the node might be evicted from the cluster due to the inconsistency voting protocol.

Percona Server for MySQL 8.4 also introduces several DDL (Data Definition Language) enhancements that are not supported in 8.0. If you try to run these DDL statements on 8.0, you’ll get errors. A key difference is:

Foreign Keys Referencing Non-Unique or Partial Keys:
- 8.4: Supports foreign keys referencing non-unique or partial keys.
- 8.0: Doesn’t allow this and will fail the DDL statement.

mysql> CREATE TABLE parent (
    id INT,
    value INT,
    INDEX (value)
);

mysql> CREATE TABLE child (
    id INT,
    parent_value INT,
    FOREIGN KEY (parent_value) REFERENCES parent(value)
);

Here, parent.value is indexed but not unique. In 8.4, the foreign key reference is allowed, but in 8.0, this operation fails.

Since DDL is replicated as a TOI (transactional operation), it gets executed on all nodes. If it succeeds on 8.4 but fails on 8.0, the cluster will detect the inconsistency and evict the 8.0 node.

In a mixed-version cluster, it’s better to use the lower version node as the writer. When executing DDL, make sure it behaves the same way on all nodes.

Major upgrade scenarios¶

Before upgrading your Percona XtraDB Cluster (PXC) to version 8.4, check your current version. You must run version 8.0 before upgrading to 8.4 - direct upgrades from older versions don’t work. Here’s what you need to know:

If you run version 8.0, you can upgrade directly to 8.4
If you run a version older than 8.0, first upgrade to the latest 8.0 release

The exact upgrade steps depend on your cluster setup and database activity. Your specific configuration and workload will shape the upgrade process, so you’ll need to plan accordingly.

In-place rolling upgrade¶

If you want to upgrade an N-node Percona Server for MySQL cluster with minimal downtime, you can use an in-place rolling upgrade. This process updates the nodes one at a time. While upgrading, make sure your application sends writes only to lower-version nodes. You can use any node for reads.

Before upgrading, verify your application can function with a reduced cluster size. When a cluster operates with an even number of nodes, split-brain scenarios become possible.

The upgrade process automatically detects the 8.0 data directory and initiates the upgrade during node bootup. The data directory transforms to be compatible with PXC 8.4. Afterward, the node joins the cluster and enters a synced state. The result is a 3-node cluster with 2 nodes running PXC 8.0 and 1 node running PXC 8.4.

Here’s how to upgrade a node from Percona XtraDB Cluster (PXC) 8.0 to 8.4:

Shut down an 8.0 node: Pick one of the nodes running PXC 8.0 and stop it.
Remove PXC 8.0 packages: Uninstall the PXC 8.0 packages, but make sure you don’t delete the data directory.
Install PXC 8.4 packages: Replace the old packages with PXC 8.4 packages.
Restart the mysqld service: Start the node again.

Downgrade¶

Starting from version 8.0.34, MySQL-compatible database servers allow downgrades within the same Long-Term Support (LTS) version scope, provided the server has not applied any new server functionality to the data. While downgrading a node is not recommended, administrators can perform the downgrade using the established procedure. The key constraint is maintaining data compatibility. New features introduced in a specific point release cannot be retroactively applied to an earlier version. Administrators must carefully verify that no version-specific modifications have been made before attempting a downgrade.

While possible, downgrades carry inherent risks and should be approached with caution and thorough planning.

Minor upgrade¶

A minor upgrade for Percona XtraDB Cluster 8.4 means upgrading to a newer version within the 8.4 series. For example, moving from version 8.4.0 to 8.4.1. These upgrades include bug fixes and small improvements but don’t change major functionality.

To upgrade the cluster, follow these steps for each node:

Make sure that all nodes are synchronized.
Stop the mysql service:
```
$ sudo service mysql stop
```
Upgrade Percona XtraDB Cluster packages. For more information, see Install Percona XtraDB Cluster.
Back up grastate.dat, so that you can restore it if it is corrupted or zeroed out due to network issues.
Start the Percona XtraDB Cluster node with the new packages.

In most cases, starting the mysql service should run the node with your previous configuration. For more information, see Adding Nodes to Cluster.
```
$ sudo service mysql start
```
On Red Hat Enterprise Linux, the /etc/my.cnf configuration file is renamed to my.cnf.rpmsave. Make sure to rename this file back to the original name before joining the upgraded node back to the cluster.

The node automatically upgrades its data directory.

This upgrade happens in one of two ways:
- During the node startup process
- Through a state transfer (either IST or SST) from another node
The cluster handles the upgrade process automatically - you need to start the node with the new packages installed, and PXC manages the data directory upgrade process.
Repeat this procedure for the next node in the cluster until you upgrade all nodes.

Get expert help¶

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services.

Community Forum Get a Percona Expert

Last update: 2025-01-16