diff --git a/docs/index-contents.md b/docs/index-contents.md index 5d18a5d5..b429c319 100644 --- a/docs/index-contents.md +++ b/docs/index-contents.md @@ -33,6 +33,7 @@ - [Install Percona XtraDB Cluster](install-index.md) - [Load balance with ProxySQL](load-balance-proxysql.md) - [Load balancing with HAProxy](haproxy.md) + - [Migrate from MySQL Galera Cluster to Percona XtraDB Cluster](migrate-mysql-galera.md) - [Monitor the cluster](monitoring.md) - [Non-Blocking Operations (NBO) method for Online Scheme Upgrades (OSU)](nbo.md) - [Online schema upgrade](online-schema-upgrade.md) diff --git a/docs/migrate-mysql-galera.md b/docs/migrate-mysql-galera.md new file mode 100644 index 00000000..c50dbb1c --- /dev/null +++ b/docs/migrate-mysql-galera.md @@ -0,0 +1,590 @@ +# 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. + +--8<--- "get-help-snip.md" + +## 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 :octicons-link-external-16:](https://docs.percona.com/percona-xtrabackup/), [Percona Monitoring and Management :octicons-link-external-16:](https://docs.percona.com/percona-monitoring-and-management/), and [Percona Toolkit :octicons-link-external-16:](https://docs.percona.com/percona-toolkit/). | + +!!! warning "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](upgrade-guide.md) 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](#migrate-during-a-maintenance-window). + +Stop the cluster, replace packages on all nodes, then bootstrap Percona XtraDB Cluster. + +!!! warning "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](https://perconadev.atlassian.net/browse/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](get-started-cluster.md) 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: + + ```sql + SELECT VERSION(); + SHOW GLOBAL STATUS LIKE 'wsrep_provider_version'; + SHOW GLOBAL STATUS LIKE 'wsrep_protocol_version'; + ``` + +2. Record cluster membership and health: + + ```sql + 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: + + ```sql + 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](garbd-howto.md)), 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 {{vers}}](upgrade-guide.md#important-changes-in-percona-xtradb-cluster-84) before any later upgrade to {{vers}}. + +## 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 {{vers}}, [`pxc_encrypt_cluster_traffic`](encrypt-traffic.md#encrypt-pxc-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](encrypt-traffic.md). + +### PXC Strict Mode + +[PXC Strict Mode](strict-mode.md) 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](xtrabackup-sst.md). + +## 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 + +!!! warning "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 :octicons-link-external-16:](https://docs.percona.com/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: + + ```shell + 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: + + ```text + [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](encrypt-traffic.md). + + Store certificates outside the data directory. + + One common path is `/etc/mysql/certs`. + +See [Configure nodes for write-set replication](configure-nodes.md) 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: + + ```shell + 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. + + === "Debian or Ubuntu" + + List installed Galera and MySQL packages: + + ```shell + dpkg -l | grep -E 'mysql|galera|wsrep' + ``` + + Remove the MySQL Galera server packages. + + Adjust names to match what you found: + + ```shell + 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](apt.md): + + ```shell + 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. + + === "Red Hat Enterprise Linux" + + List installed packages: + + ```shell + rpm -qa | grep -Ei 'mysql|galera|wsrep' + ``` + + Remove MySQL Galera packages without removing unrelated dependencies. + + Example: + + ```shell + 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](yum.md): + + ```shell + 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: + + ```shell + sudo systemctl start mysql@bootstrap.service + ``` + + See [Bootstrap the first node](bootstrap.md). + +3. Verify the bootstrap node is `Synced` and `Primary`: + + ```sql + SHOW STATUS LIKE 'wsrep%'; + ``` + +4. Start the second node with a normal start (not bootstrap): + + ```shell + 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`: + + ```shell + 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: + + ```sql + 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: + + ```sql + SELECT VERSION(); + ``` + + The version string must identify Percona XtraDB Cluster or Percona Server for MySQL. + +3. [Verify replication](verify-replication.md) 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. + +## Task 7: Update related systems + +{.power-number} + +1. Configure monitoring for the nodes. + + [Percona Monitoring and Management :octicons-link-external-16:](https://docs.percona.com/percona-monitoring-and-management/) is the recommended option for PXC. + + See also [Monitor the cluster](monitoring.md). + +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 {{vers}} defaults to `caching_sha2_password`. + + Use ProxySQL 2.6.2 or later. + + See [Load balance with ProxySQL](load-balance-proxysql.md). + +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](xtrabackup-sst.md), donor error log | +| Application errors after migration | Strict Mode rejects statements | `pxc_strict_mode`, [Strict Mode](strict-mode.md), 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](failover.md) and [Emergency quorum recovery](emergency-quorum-recovery.md). | + +## 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 {{vers}}). + + Use [Upgrade Percona XtraDB Cluster](upgrade-guide.md). + +* Review [Percona XtraDB Cluster limitations](limitation.md) with your application team. + + Remove unsupported patterns on purpose. + +For help with migration scope or high availability review, see [Get help from Percona](get-help.md). + +!!! admonition "See also" + + * [How to Migrate from MySQL Galera Cluster to Percona XtraDB Cluster :octicons-link-external-16:](https://www.percona.com/blog/migrate-mysql-galera-cluster-to-percona-xtradb-cluster/) + + * [Upgrade Percona XtraDB Cluster](upgrade-guide.md) + + * [Get started with Percona XtraDB Cluster](get-started-cluster.md) diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md index 84562598..930ac01e 100644 --- a/docs/upgrade-guide.md +++ b/docs/upgrade-guide.md @@ -5,6 +5,8 @@ This guide describes how to upgrade Percona XtraDB Cluster to version 8.4 without downtime. A rolling upgrade updates one node at a time while the cluster remains operational. Rolling upgrades to 8.4 require version 8.0 or later. Upgrade to the latest 8.0 release before upgrading to 8.4. +If you are moving from MySQL Galera Cluster (mysql-wsrep) to Percona XtraDB Cluster, use [Migrate from MySQL Galera Cluster to Percona XtraDB Cluster](migrate-mysql-galera.md) first. Complete that distribution change on a matching major version, then return here for any major-version upgrade. + !!! warning A node with a newer protocol version cannot join a cluster running an older Galera Communication System (GCS) protocol version. The cluster enforces this rule to prevent data corruption and incompatibility issues. diff --git a/mkdocs-base.yml b/mkdocs-base.yml index b9df30e1..752d11d1 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -210,6 +210,7 @@ nav: - verify-replication.md - Upgrade: - upgrade-guide.md + - migrate-mysql-galera.md - upgrade-backup.md - upgrade-packages.md - PXC security: