Migrate from MySQL Galera Cluster to Percona XtraDB Cluster¶

Percona XtraDB Cluster (PXC) uses the same write-set replication model as MySQL Galera Cluster, so a migration replaces the binaries and keeps the datadir. The schemas, data, user accounts, and privileges carry over.

Starting in PXC 8.4.11, a PXC node can join a running MySQL Galera Cluster. You can convert nodes one at a time, in place, so the cluster stays available throughout and no extra hardware is required.

You can use either of the following methods:

Stop one node in an N-node Galera Cluster, replace the binaries with PXC, start PXC on the existing datadir, and let that node rejoin
Add a new PXC node to the Galera Cluster

Both approaches keep the cluster available. Earlier PXC versions cannot form a mixed cluster with Galera Cluster, so those migrations need a short full-cluster outage.

Set these before you start a PXC node

Use wsrep_sst_method=xtrabackup-v2. PXC requires this SST method.
PXC encrypts the Galera channel by default. Set pxc_encrypt_cluster_traffic so it matches the Galera Cluster before you start the PXC node.

Review Get more help for ways that we can work with you.

Back up your data before you start

Create and verify a physical backup with Percona XtraBackup before you change any node. A backup is the only reliable way back if a step fails.

Before you start¶

An N-node MySQL Galera Cluster where every node is Synced and the cluster is Primary.
PXC packages for your platform. See Install on Debian or Ubuntu or Install on Red Hat Enterprise Linux.
Root or sudo access on every node.

Reuse the Galera Cluster my.cnf. Keep wsrep cluster identity the same (wsrep_cluster_name, wsrep_cluster_address, and the per-node wsrep_node_name and wsrep_node_address), then change only what PXC requires:

wsrep_sst_method=xtrabackup-v2. PXC uses Percona XtraBackup for SST. Do not carry over rsync, MariaBackup, or a custom SST script. See Percona XtraBackup SST configuration.
wsrep_provider must point at the PXC Galera library. See Configure nodes for write-set replication.
pxc_encrypt_cluster_traffic must match the Galera Cluster. PXC enables it by default.

Traffic encryption

PXC enables pxc_encrypt_cluster_traffic by default. If your Galera Cluster does not encrypt replication traffic, set pxc_encrypt_cluster_traffic=OFF on the PXC nodes. Otherwise, distribute identical certificates to every node. See Encrypt PXC traffic.

Migrate with PXC 8.4.11 or newer¶

Introduced in Percona XtraDB Cluster 8.4.11, you can join a running Galera Cluster. Choose either scenario. Both keep the cluster available throughout.

Scenario 1: Convert each node in place¶

The node keeps its datadir, so it rejoins with IST instead of a full data copy. This scenario needs no extra hardware.

Stop one Galera Cluster node.
Install PXC on that host. Keep the Galera Cluster my.cnf, apply the adjustments in Before you start, and start the node. It joins the cluster with IST.
Wait for the node to reach Synced, then repeat steps 1 and 2 on the next node.

Scenario 2: Add PXC nodes and retire Galera Cluster nodes¶

Use this scenario when you also move to new hosts. Each new node joins with SST, so plan for the transfer time and the load on the donor.

Start a fresh PXC node and join it to the existing Galera Cluster. Copy the Galera Cluster my.cnf, apply the same adjustments, and start the node. It joins with SST.
Wait for the new node to reach Synced.
Decommission one Galera Cluster node.
Repeat steps 1 through 3 until every Galera Cluster node is replaced.

Migrate with PXC earlier than 8.4.11¶

These PXC versions cannot form a cluster with Galera Cluster nodes, so you bootstrap a new cluster from an existing datadir during a maintenance window.

Stop application writes, then stop MySQL on all Galera Cluster nodes.
Using the datadir of the last node you stopped, bootstrap a new cluster with the PXC binaries:
```
sudo systemctl start [email protected]
```
See Bootstrap the first node.
Delete the grastate.dat file from the datadir of every other node. This forces those nodes to join with SST.
Start the other nodes one at a time with a normal start. Wait for each node to reach Synced before you start the next one.
```
sudo systemctl start mysql
```
Stop the bootstrap unit on the first node and start it normally so it uses wsrep_cluster_address:
```
sudo systemctl stop [email protected]
sudo systemctl start mysql
```

Verify the migration¶

Run these checks on every node:

SELECT VERSION();
SHOW STATUS LIKE 'wsrep_cluster_status';
SHOW STATUS LIKE 'wsrep_cluster_size';
SHOW STATUS LIKE 'wsrep_local_state_comment';

VERSION() must identify Percona XtraDB Cluster, wsrep_cluster_status must be Primary, wsrep_local_state_comment must be Synced, and wsrep_cluster_size must equal your node count.

Then verify replication with a write on one node and a read on the others.

After you migrate¶

PXC Strict Mode defaults to ENFORCING and blocks unsupported operations. If your workload needs it, start with PERMISSIVE, validate the application, then move to ENFORCING. See Percona XtraDB Cluster strict mode.
Replace a Codership garbd arbitrator with the matching Percona package. See Set up Galera arbitrator.
Point backup jobs and monitoring at the new cluster. Percona Monitoring and Management is the recommended option. See Monitor the cluster.
Keep the pre-migration backup until the cluster runs cleanly in production for an agreed observation period.

To change major versions, complete the migration first, then use Upgrade Percona XtraDB Cluster.

Troubleshooting¶

Symptom	Likely cause	What to check
Node fails to join	Encryption mismatch	`pxc_encrypt_cluster_traffic` must match on every node. Certificates must be identical. See Encrypt PXC traffic.
Node starts its own cluster	Wrong `wsrep_cluster_address` or an accidental bootstrap	Bootstrap only one node, and only when you form a new cluster.
SST fails	Unsupported SST method	`wsrep_sst_method` must be `xtrabackup-v2`. See `wsrep_sst_allowed_methods` and XtraBackup SST configuration.
Client login fails	Authentication plugin mismatch	Accounts keep the plugin stored in `mysql.user`. Older connectors need TLS or RSA key exchange for `caching_sha2_password`. With ProxySQL, use 2.6.2 or later. See Load balance with ProxySQL.
Application errors after migration	Strict Mode rejects statements	`pxc_strict_mode` and the error log. See Percona XtraDB Cluster strict mode.
Configuration missing after a yum or dnf install	RHEL replaced `my.cnf`	Restore your settings from `/etc/my.cnf.rpmsave`.
Cluster size does not recover	Quorum loss	See Cluster failover and Emergency quorum recovery.