Skip to content
Percona Software for MySQL Documentation
Rate this page
☆ ☆ ☆ ☆ ☆
Thanks for your feedback
Thank you! The feedback has been submitted.

Get free database assistance or contact our experts for personalized support.

Get help from Percona

Migrate from MySQL Galera Cluster to Percona XtraDB Cluster

Migrate an existing MySQL Galera Cluster (Codership MySQL-wsrep build) to Percona XtraDB Cluster (PXC).

Schema, system tables, and user accounts typically carry over with the data directory.

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

Prerequisites

Complete the following tasks before you start:

  • Stop and start MySQL services

  • Edit my.cnf or the equivalent file on your system

  • Create and restore backups

  • Use Galera status variables, State Snapshot Transfer (SST), and quorum

What changes and what does not

Area Result
Database engine MySQL-compatible. PXC runs on Percona Server for MySQL. Applications and schemas work without a rewrite. A return to Oracle MySQL after you use Percona features is not a simple reverse of this migration.
Schema and data Carry over. Recreate schemas or reload data only for a restore-based cutover.
User accounts and privileges Carry over with the data directory.
Clustering model Same Galera write-set replication model on the Percona Galera fork.
Configuration Update Galera library paths, SST settings, and PXC defaults for traffic encryption and Strict Mode.
Tools Use Percona XtraBackup , Percona Monitoring and Management , and Percona Toolkit .

Do not change major versions during the migration

Match PXC to your MySQL major version.

For example, migrate MySQL Galera 8.0 to PXC 8.0 first.

After the cluster is stable on PXC, follow Upgrade Percona XtraDB Cluster for an upgrade to 8.4.

A migration and a major-version change in one step raise risk and make troubleshooting harder.

Migration method

Use a maintenance-window cutover.

Stop the cluster, replace packages on all nodes, then bootstrap Percona XtraDB Cluster.

Rolling and in-place migration are not supported

You cannot replace one MySQL Galera node with PXC and rejoin that node to a mixed cluster.

Work to enable rolling and in-place migration is tracked in PXC-5286.

That work is planned for a future 8.4 and 9.7 release.

Do not attempt a rolling package swap on a production cluster.

Preparation for the maintenance-window cutover includes the following:

  • Inventory

  • Staging rehearsal

  • Verified backup

Before you begin

Complete these items before any production change:

  • Root or sudo access on every cluster node

  • A maintenance plan and a tested rollback path (verified backup or an untouched source cluster)

  • Open network ports for Galera and MySQL: 3306, 4444, 4567, 4568

  • Disk space for a full backup and temporary SST traffic

  • Application owners ready to validate reads and writes after cutover

Note

Plan for a full cluster outage during the maintenance window.

See Get started with Percona XtraDB Cluster for cluster sizing guidance after the migration.

Task 1: Inventory your current cluster

Record the cluster state.

Use the record to choose a compatible PXC release and to keep required settings.

{.power-number}

  1. On every node, record the MySQL and Galera versions:

    SELECT VERSION();
SHOW GLOBAL STATUS LIKE 'wsrep_provider_version';
SHOW GLOBAL STATUS LIKE 'wsrep_protocol_version';

  2. Record cluster membership and health:

    SHOW GLOBAL STATUS LIKE 'wsrep_cluster_size';
SHOW GLOBAL STATUS LIKE 'wsrep_cluster_status';
SHOW GLOBAL STATUS LIKE 'wsrep_local_state_comment';
SHOW GLOBAL STATUS LIKE 'wsrep_ready';

    Healthy nodes report Primary, Synced, and ON.

  3. Export the Galera configuration you must keep:

    SHOW VARIABLES LIKE 'wsrep%';
SHOW VARIABLES LIKE 'pxc%';

    Save a copy of each node configuration file.

    Common paths include /etc/my.cnf and /etc/mysql/mysql.conf.d/mysqld.cnf.

  4. Record topology details:

    • Hostnames and IP addresses for every node

    • Galera arbitrator use (garbd), if any

    • Load balancer or proxy in front of the cluster (ProxySQL or HAProxy)

    • SST method and credentials

    • Replication traffic encryption status

    • Async replicas that read from a Galera node

  5. Confirm the target PXC version matches your MySQL major version.

    Review Important changes in Percona XtraDB Cluster 8.4 before any later upgrade to 8.4.

Task 2: Plan for PXC defaults that differ from MySQL Galera

PXC enables security and safety settings that many MySQL Galera deployments leave off.

Plan for these settings before the first package swap.

Traffic encryption

In PXC 8.4, pxc_encrypt_cluster_traffic is enabled by default.

A PXC node that expects encrypted replication traffic cannot join a cluster that uses unencrypted Galera traffic.

For a maintenance-window cutover, distribute identical certificates to every node before you bootstrap PXC.

Enable pxc_encrypt_cluster_traffic when you start the PXC cluster.

See Encrypt PXC traffic.

PXC Strict Mode

PXC Strict Mode defaults to ENFORCING and blocks unsupported operations.

If the workload uses features that Strict Mode rejects, start migrated nodes with PERMISSIVE or MASTER.

Validate the application.

Then set Strict Mode to ENFORCING.

Galera library path and SST method

Update the following settings when you move to PXC:

  • Set wsrep_provider to the Percona Galera 4 library:

    • Debian or Ubuntu: /usr/lib/galera4/libgalera_smm.so

    • Red Hat Enterprise Linux (RHEL) derived systems: /usr/lib64/galera4/libgalera_smm.so

  • Set wsrep_sst_method=xtrabackup-v2.

    PXC uses Percona XtraBackup for SST.

    Configure SST authentication as described in Percona XtraBackup SST configuration.

Task 3: Build a staging cluster and rehearse

Do not run the first migration attempt on production.

{.power-number}

  1. Build a staging cluster that mirrors production node count, MySQL and Galera version, disk layout, and key wsrep_* settings.

  2. Restore a recent production backup into staging.

    You can also clone production with an approved method.

  3. Rehearse the full maintenance-window cutover on staging.

  4. Run basic application tests:

    • Logins

    • Writes

    • Schema changes you run in production

    • Backup and restore

    • Failover of one node

  5. Time each step.

    Use those times to size the production maintenance window.

  6. Practice rollback.

    Restore from backup, or return to the pre-migration packages and data, until the procedure is reliable.

Task 4: Create a verified backup

Required: Create a backup before migrating

Create and verify a backup before you remove any MySQL Galera packages.

{.power-number}

  1. Create a full backup with Percona XtraBackup or another proven physical backup method.

  2. Store the backup off the cluster nodes when possible.

  3. Restore the backup to a scratch host.

    Confirm that MySQL starts and that critical schemas are present.

  4. Keep this backup until the migrated PXC cluster runs cleanly in production for an agreed observation period.

Task 5: Prepare the PXC configuration

Prepare a configuration that keeps your cluster identity and matches PXC defaults.

Complete this work before you install PXC packages on a node.

{.power-number}

  1. Copy the MySQL Galera configuration to a backup file:

    sudo cp /etc/my.cnf /etc/my.cnf.galera.bak

    Use the path for your distribution if the path differs.

  2. Keep these values consistent across the migration:

    • wsrep_cluster_name

    • wsrep_cluster_address (all node addresses)

    • wsrep_node_name and wsrep_node_address (per node)

    • server-id (unique per node when you use async replication)

  3. Update Galera and PXC settings.

    Example fragment:

    [mysqld]
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2

wsrep_provider=/usr/lib64/galera4/libgalera_smm.so
wsrep_cluster_name=my-cluster
wsrep_cluster_address=gcomm://192.168.70.61,192.168.70.62,192.168.70.63
wsrep_node_name=node1
wsrep_node_address=192.168.70.61

wsrep_sst_method=xtrabackup-v2
# Configure SST user credentials per xtrabackup-sst.md

pxc_strict_mode=PERMISSIVE

    On Debian or Ubuntu, set wsrep_provider=/usr/lib/galera4/libgalera_smm.so.

  4. If you enable encryption, place identical certificates on every node.

    Configure the certificates as described in Encrypt PXC traffic.

    Store certificates outside the data directory.

    One common path is /etc/mysql/certs.

See Configure nodes for write-set replication for a full configuration procedure.

Migrate during a maintenance window

Plan a full cluster outage for this cutover.

Do not delete the data directory when you remove MySQL Galera packages.

Stop write traffic on the cluster

{.power-number}

  1. Announce the maintenance window and stop application writes.

    You can also stop the application.

  2. Confirm all nodes are Synced.

  3. Create a final backup if the previous backup does not meet your recovery point objective.

  4. Stop MySQL on all nodes.

    Start with non-primary writers if your runbook requires an order:

    sudo systemctl stop mysql

    If your service unit name differs (for example mysqld), use that name.

Convert every node to PXC

On each node, complete the following steps.

Package names for MySQL Galera (mysql-wsrep) vary by vendor and operating system.

Identify installed packages first.

Then remove only the server packages.

Do not remove the data directory.

{.power-number}

  1. Copy the configuration to a backup file and note the data directory path (often /var/lib/mysql).

  2. Remove MySQL Galera packages and install PXC.

    List installed Galera and MySQL packages:

    dpkg -l | grep -E 'mysql|galera|wsrep'

    Remove the MySQL Galera server packages.

    Adjust names to match what you found:

    sudo apt-get remove mysql-wsrep-server mysql-wsrep-client

    Do not run purge commands against the data directory.

    Prefer remove over purge until configuration backups exist.

    Install Percona XtraDB Cluster from the Percona repository.

    See Install on Debian or Ubuntu:

    sudo percona-release setup pxc-84-lts
sudo apt update
sudo apt install -y percona-xtradb-cluster

    Use the repository that matches your target major version.

    For example, use PXC 8.0 when you migrate from MySQL Galera 8.0.

    List installed packages:

    rpm -qa | grep -Ei 'mysql|galera|wsrep'

    Remove MySQL Galera packages without removing unrelated dependencies.

    Example:

    sudo rpm -e --nodeps mysql-wsrep-server mysql-wsrep-client

    Adjust package names to match your inventory.

    Do not delete /var/lib/mysql.

    Install Percona XtraDB Cluster.

    See Install on Red Hat Enterprise Linux:

    sudo percona-release setup pxc-84-lts
sudo yum install -y percona-xtradb-cluster

    On RHEL 8 and RHEL 9, disable the default mysql module first if the module hides Percona packages.

    On RHEL-derived systems, the installer may save the previous configuration as /etc/my.cnf.rpmsave and install a default /etc/my.cnf.

    Restore your prepared PXC settings before you start the node.

  3. Install your prepared PXC configuration on every node.

    Keep wsrep_cluster_name and node addresses consistent.

  4. Distribute encryption certificates before bootstrap if you enable pxc_encrypt_cluster_traffic.

Bootstrap and form the PXC cluster

{.power-number}

  1. Choose the node with the most current data.

    Any node that was Synced when you stopped the cluster is a valid choice.

    That node becomes the bootstrap node.

  2. Bootstrap the first node:

    sudo systemctl start mysql@bootstrap.service

    See Bootstrap the first node.

  3. Verify the bootstrap node is Synced and Primary:

    SHOW STATUS LIKE 'wsrep%';

  4. Start the second node with a normal start (not bootstrap):

    sudo systemctl start mysql

  5. Wait until the second node reaches Synced.

    Then start the third node the same way.

  6. After the cluster has at least two members, stop the bootstrap unit on the first node and start the node normally.

    The node then uses the standard wsrep_cluster_address:

    sudo systemctl stop mysql@bootstrap.service
sudo systemctl start mysql

  7. Confirm wsrep_cluster_size matches the number of nodes you expect.

  8. Set pxc_strict_mode to ENFORCING after application testing succeeds.

Task 6: Validate the migrated cluster

Run these checks before you mark the migration complete.

{.power-number}

  1. On every node, confirm cluster health:

    SHOW STATUS LIKE 'wsrep_cluster_status';
SHOW STATUS LIKE 'wsrep_local_state_comment';
SHOW STATUS LIKE 'wsrep_ready';
SHOW STATUS LIKE 'wsrep_cluster_size';

  2. Confirm the nodes run PXC binaries:

    SELECT VERSION();

    The version string must identify Percona XtraDB Cluster or Percona Server for MySQL.

  3. Verify replication with a small write on one node and a read on the other nodes.

  4. Test failover:

    • Remove one node from the proxy pool

    • Stop MySQL on that node

    • Confirm the application still works

    • Start the node and wait for Synced

  5. Run application acceptance tests against the proxy endpoint.

    Do not test only against a single node.

  6. Create a post-migration backup and verify the backup.

  7. Watch error logs and flow control for several hours after cutover.

    Include peak traffic when possible.

{.power-number}

  1. Configure monitoring for the nodes.

    Percona Monitoring and Management is the recommended option for PXC.

    See also Monitor the cluster.

  2. Update backup jobs to use Percona XtraBackup versions that match your PXC series.

  3. If you use ProxySQL, confirm health checks and users still work.

    PXC 8.4 defaults to caching_sha2_password.

    Use ProxySQL 2.6.2 or later.

    See Load balance with ProxySQL.

  4. Enable async replicas only after you verify replication compatibility with the migrated donor.

  5. Remove MySQL Galera packages and vendor repositories from the hosts.

    Later upgrades must pull only Percona packages.

Rollback

Select a rollback method during planning.

Keep the method available until the observation period ends.

Situation Rollback approach
Migration not yet started No action. Keep the verified backup.
Cutover failed during the maintenance window Restore the verified pre-migration backup to MySQL Galera nodes, or return to the untouched source cluster if you migrated from a parallel environment.
Data was written on PXC after cutover A package downgrade does not keep those writes. Restore from a backup taken after the writes, or use a planned data recovery process.

Warning

Package downgrades after data dictionary or privilege table changes are unsafe.

Prefer restore from backup over ad-hoc package reversals.

Troubleshooting checklist

Symptom Likely cause What to check
Node fails to join after package swap Encryption mismatch pxc_encrypt_cluster_traffic, identical certificates on all nodes
Node starts as a standalone cluster Wrong wsrep_cluster_address or accidental bootstrap Configuration file. Avoid mysql@bootstrap except for the first node of a cluster.
SST fails XtraBackup or SST user privileges XtraBackup SST configuration, donor error log
Application errors after migration Strict Mode rejects statements pxc_strict_mode, Strict Mode, error log
Configuration missing after yum or dnf install RHEL replaced my.cnf Restore from my.cnf.rpmsave or your .galera.bak copy
Cluster size does not recover Quorum loss Bring back enough nodes. See Cluster failover and Emergency quorum recovery.

After a successful migration

  • Keep the pre-migration backup until you pass your production observation period.

  • Schedule the next maintenance window for any major-version upgrade that remains (for example 8.0 to 8.4).

    Use Upgrade Percona XtraDB Cluster.

  • Review Percona XtraDB Cluster limitations with your application team.

    Remove unsupported patterns on purpose.

For help with migration scope or high availability review, see Get help from Percona.

See also