Move from MySQL to MariaDB Server seamlessly. This section provides detailed instructions, tools, and best practices for migrating your databases and applications with ease.
A strategy for migrating from a MySQL Galera Cluster to a MariaDB Galera Cluster by setting up the new cluster as an asynchronous replica, minimizing downtime.
This guide details migrating a live database from a MySQL Galera Cluster to a . The migration strategy requires setting up a new MariaDB Cluster and using to sync it with the existing MySQL Cluster. The method includes a reliable failback route.
MySQL Server: A running MySQL Galera Cluster (version 8.0 or 8.4) to migrate.
MariaDB Server: The target . This guide assumes the latest stable version.
mysqldump: A command-line utility by MySQL to create initial database backup.
Due to changes in MySQL 8.0+, mariadb-dump may not be compatible for this initial step.
Root or Sudo Access: Administrative are required on all servers involved in the migration.
Version Compatibility: Select a with your MySQL version for replication.
Feature Differences: Review the to identify any deprecated features or changes in system tables, user accounts, and authentication that might affect your setup.
Replication Compatibility
5.7
10.2 and newer
8.0
10.6.21, 10.11.11, 11.4.5, 11.7.2 and newer
For more details, see y.
Set up a new, empty that will become the target for the migration.
Install MariaDB Server and Galera Provider
Install MariaDB Server package and Galera wsrep provider library on each node of the new cluster. Refer and for detailed instructions.
Configure Each MariaDB Node
at /etc/mysql/conf.d/galera.cnf on each node. The configuration will be mostly identical across nodes, except for node-specific details like wsrep_node_name and wsrep_node_address.
Example galera.cnf:
A full logical backup of the MySQL database is required to seed the new MariaDB Cluster.
Enable Binary Logging on MySQL
requires the to be enabled on the MySQL source. If not enabled, enable it on at least one node in your MySQL cluster.
Edit my.cnf: In the [mysqld] section of your , add log-bin=mysql-bin.
Restart MySQL: A server restart is required for the change to take effect.
Restarting MySQL will cause a brief outage for the node.
Create the Backup with mysqldump
Use mysqldump from the source MySQL server to create a full backup. Using --all-databases and --master-data will include all databases and the binary log position needed to start replication.
Start the first node of the MariaDB cluster and load the MySQL backup.
Bootstrap the First Node
Start the first MariaDB node with the --wsrep-new-cluster option. This initializes the cluster.
Load the Backup File
Transfer the backup.sql file to the first MariaDB node and import it:
Start Subsequent Nodes
Start the MariaDB service normally on the remaining nodes. They will connect to the first node, and a State Snapshot Transfer (SST) will automatically sync their data.
Verify the Cluster
Connect to any node and check the cluster size to ensure all nodes have joined successfully.
Configure one of the MariaDB nodes to act as a replica of the source MySQL cluster.
Create a Replication User on MySQL
On the MySQL source node where binlogging is enabled, create a dedicated user for replication.
Configure the MariaDB Replica
On one of the MariaDB nodes, configure and start the . Use the binary log file and position noted from the mysqldump output (MASTER_LOG_FILE and MASTER_LOG_POS) or use GTID-based replication.
With replication running, the MariaDB cluster will catch up with any changes made to the MySQL cluster since the backup was taken.
Monitor Replication Lag
Check the replica status on the MariaDB node to ensure it is synchronized.
Ensure the following conditions are met on the replica:
Slave_IO_Running: Yes
Slave_SQL_Running: Yes
Seconds_Behind_Master: 0
A Seconds_Behind_Master value of 0 indicates the replica is completely synchronized.
Perform the Failover
Once the MariaDB cluster is fully synchronized, follow these steps:
Stop Application Traffic: Cease traffic to the MySQL cluster.
Verify Synchronization: Confirm the MariaDB replica has processed all events from the MySQL binary log.
Promote MariaDB:
Stop replication on the MariaDB node using STOP SLAVE;
Update your application to connect to the MariaDB Galera Cluster.
Resume Application Traffic: Redirect traffic to the MariaDB cluster.
Decommission MySQL: After confirming the application runs smoothly on MariaDB, decommission the MySQL cluster.
[mysqld]
# MariaDB settings
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
bind-address=0.0.0.0
# Galera Provider Configuration
wsrep_on=ON
wsrep_provider=/usr/lib/galera/libgalera_smm.so # Adjust path if necessary
# Galera Cluster Configuration
wsrep_cluster_name="new_mariadb_cluster"
wsrep_cluster_address="gcomm://node1_ip,node2_ip,node3_ip"
# Node-specific Configuration
wsrep_node_name="mariadb_node1"
wsrep_node_address="node1_ip"
# SST Configuration
wsrep_sst_method=mariadb-backup
mysqldump --user=backup_user --password --all-databases --master-data=2 > /path/to/backup.sqlsudo galera_new_clustermariadb -u root -p < /path/to/backup.sqlsudo systemctl start mariadbSHOW STATUS LIKE 'wsrep_cluster_size';CREATE USER 'repl_user'@'mariadb_node_ip' IDENTIFIED BY 'your_password';
GRANT REPLICATION SLAVE ON *.* TO 'repl_user'@'mariadb_node_ip';CHANGE MASTER TO
MASTER_HOST='mysql_source_ip',
MASTER_PORT=3306,
MASTER_USER='repl_user',
MASTER_PASSWORD='your_password',
MASTER_USE_GTID=slave_pos;
START SLAVE;SHOW SLAVE STATUS\GOutdated page regarding migrating from MySQL to MariaDB Server. While potentially outdated, these resources may offer historical context or insights for specific scenarios.
There is a screencast for upgrading from MySQL 5.1.55 to MariaDB. Watch this example to see how easy this process is. It really is just a "drop in replacement" to MySQL.
This page is licensed: CC BY-SA / Gnu FDL
Outdated page regarding migrating from MySQL to MariaDB Server. While potentially outdated, these resources may offer historical context or insights for specific scenarios.
If you upgrade to from MySQL 5.1 you don't have to do anything with your data or MySQL clients. Things should "just work".
When upgrading between different major versions of MariaDB or MySQL you need to run the mysql_upgrade program to convert data that are incompatible between versions. This will also update your privilege tables in the mysql database to the latest format.
In almost all cases mysql_upgrade should be able to convert your tables, without you having to dump and restore your data.
After installing MariaDB, just do:
If you want to run with a specific TCP/IP port do:
If you want to connect with a socket do:
To see other options, use --help.
"mysql_upgrade" reads the my.cnf sections [mysql_upgrade] and [client] for default values.
There are a variety of reasons tables need to be converted; they could be any of the following:
The collation (sorting order) for an index column has changed
A field type has changed storage format
and changed format between MySQL 4.1 and MySQL 5.0
An engine has a new storage format
SHOW TABLES until you convert them.If you don't convert the tables, one of the following things may happen:
You will get warnings in the error log every time you access a table with an invalid (old) file name.
When searching on key values you may not find all rows
You will get an error "ERROR 1459 (HY000): Table upgrade required" when accessing the table.
You may get crashes
"mysql_upgrade" works by calling mysqlcheck with different options and running the "mysql_fix_privileges" script. If you have trouble with "mysql_upgrade", you can run these commands separately to get more information of what is going on.
Most of the things in the section also applies to MariaDB.
The following differences exists between "mysql_upgrade" in MariaDB and MySQL (as of ):
MariaDB will convert long table names properly.
MariaDB will convert tables (no need to do a dump/restore or ).
MariaDB will convert old archive tables to the new 5.1 format (note: new feature in testing).
"mysql_upgrade --verbose" will run "mysqlcheck --verbose" so that you get more information of what is happening.
This page is licensed: CC BY-SA / Gnu FDL
mysql_upgrade --verbosemysql_upgrade --host=127.0.0.1 --port=3308 --protocol=tcpmysql_upgrade --socket=127.0.0.1 --protocol=socketARCHIVE changed storage format between 5.0 and 5.1
The format for storing table names has changed
In MySQL 5.1 table names are encoded so that the file names are identical on all computers. Old table names that contains forbidden file name characters will show up prefixed with #mysql50
Instructions for a rolling migration where individual nodes in a MySQL cluster are taken offline, wiped, and replaced with MariaDB nodes, eventually forming a new cluster.
Version Requirement
This guide provides instructions for migrating a MySQL 8.0 Galera Cluster to a MariaDB Galera Cluster 11.4. Ensure that your systems meet or exceed these version requirements before proceeding. Please refer to the for detailed version information.
The End-of-Life (EOL) date for continued maintenance and regular binary releases of MySQL Galera Cluster will be
This guide outlines the procedure for migrating a live MySQL Galera Cluster to a MariaDB Galera Cluster. It follows the process for migrating a live MySQL Galera Cluster to a MariaDB Galera Cluster by replacing the binaries on each node sequentially. This "In-Place" method maintains cluster availability during the migration, although the cluster capacity will be reduced while individual nodes are being processed.
Source: MySQL Galera Cluster 8.0.43-26.4.24 or later.
Target: MariaDB Community Server 11.4 (LTS) or later.
Library: MariaDB Galera library 26.4.24 or latest stable edition.
Tools:
mysqldump (installed with the server).
mariadb-backup (installed with MariaDB).
Access: Root access to the operating system and the database.
Cluster Backup
This migration involves uninstalling software and wiping data directories on live nodes. A full cluster backup (using Xtrabackup or Volume Snapshot) is mandatory before proceeding.
Perform these steps on the running MySQL Cluster BEFORE shutting down any nodes.
MariaDB maintains high levels of compatibility with MySQL, but you still need to to select the most suitable MariaDB version compatible with your current MySQL server.
While MariaDB and MySQL share a common history, they have diverged significantly. You must "clean" the schema and configurations to ensure data compatibility before the migration begins.
MySQL 8.0 defaults to caching_sha256_password. MariaDB does not support the caching_sha256_password authentication protocol in all released versions (which is cumbersome and not secure for in-house attacks, since clear-text passwords are available inside the server).
Support Status:
Implemented via MDEV-9804 for version 12.1.1.
Available in the CS release based on MDEV-37600.
Already supported in 11.8 Enterprise Server via MENT-2359.
Available in 11.4 Enterprise Server with the December 2025 release as a rebase of MDEV-37600.
You can check which MySQL users are using SHA-256 or caching_sha256_password by executing:
You can change the user to use a protocol compatible with both MySQL and MariaDB with:
MySQL stores JSON as a native binary type. MariaDB stores JSON as an alias for LONGTEXT with constraint checks. Galera replication may break if you attempt to replicate binary JSON objects from MySQL to MariaDB.
Check if you have tables that use the MySQL JSON type:
You can convert the JSON column to text with:
Encryption and compression table options are very different in MySQL compared to MariaDB. Logical dump will naturally de-encrypt/de-compress table contents but syntax used for creating tables is not supported by MariaDB.
For example:
leads to: ERROR 1911 (HY000) at line 1174: Unknown option 'COMPRESSION'
Therefore, encrypted/compressed tables need to be de-encrypted/de-compressed before starting the conversion, and then encrypted/compressed again afterwards using MariaDB syntax.
Detect encrypted tables:
Detect compressed tables:
Action: Run ALTER TABLE to remove the conflicting ENCRYPTION and COMPRESSION attributes. They can be re-enabled using MariaDB syntax after the full migration is complete.
MariaDB does not support MySQL general tablespaces. In MySQL, these are used to store tables in specific external files rather than the default data directory. During migration, this TABLESPACE argument is ignored.
Example Scenario: In MySQL, a user creates a custom tablespace file at a specific path and assigns a table to it:
If you examine the table definition in MySQL, you will see the tablespace assignment:
Migration Behavior: When this table is migrated to MariaDB (via mysqldump), the TABLESPACE 'ts1' attribute is ignored.
Result: The table t1 will be created as a standard file-per-table in the default MariaDB data directory (e.g., /var/lib/mysql/dbname/t1.ibd).
Loss of Path: It will not use the custom path /home/jan/galeradb/node1/ts1.ibd.sq
During cluster migration make sure that no new tablespaces are created and no new tables created inside a general tablespaces.
Ensure no XA transactions are in a PREPARED state, as these cannot be migrated cleanly.
The mysql.user system table structure differs between vendors and will not migrate automatically. You must create the SST user now so it exists in the data stream before the switch.
Ensure these settings are active on the MySQL cluster.
innodb_file_per_table = 1
This is the default setting for MySQL and MariaDB. If this is not set, you must use mysqldump for the entire migration, as specific recommendations regarding tablespaces will not work.
innodb_flush_log_at_trx_commit = 1
InnoDB writes the log buffer to the log file and flushes it to disk after every transaction commit. This is the safest option, ensuring no data loss in a crash, though it comes at the cost of slower performance due to frequent disk I/O.
gcache.size: Should be large enough to avoid SST (State Snapshot Transfer) when a node is temporarily out of the cluster. A larger cache increases the chance of a faster IST (Incremental State Transfer).
This is the most complex step. This node will bridge the gap between the MySQL cluster and the new MariaDB environment.
Once the first node (Node A) is successfully running MariaDB, you can migrate Node B, Node C, etc.
Once all nodes are running MariaDB:
Cleanup Config: Remove gcs.check_appl_proto=0 and wsrep_sst_donor from my.cnf on all nodes. Reset wsrep_sst_method to mariabackup on the first node.
Security: Run mariadb-secure-installation to secure the root account and remove anonymous users.
Features: Re-enable encryption or compression using MariaDB-supported syntax if required.
The mysql.user table structure is not fully compatible and cannot be migrated automatically.
Impact: The administrator must create necessary users for the MariaDB database manually.
Workaround: In testing, using --skip-table=mysql.user during dump/restore and manually creating the necessary SST user was required.
Reference: MDEV-33486
MariaDB currently does not support the regexp-time-limit parameter.
Impact: If this variable exists in your configuration or scripts, the server may fail to start or throw errors.
Reference: MySQL Sysvar: regexp_time_limit, MDEV-37403
MariaDB does not understand the wsrep_start_position format provided by MySQL due to GTID formatting differences.
Example: MySQL node will use a set wsrep_start_position like: ”60e63a7-734c-11f0-bd90-97669e82ccf4:2284/2281/11/0747b7c5-734c-11f0-a69b-00e04ca2f8fe”
Reference: MGL-57
Replication from MariaDB → MySQL is not supported.
Impact: During migration, there can be no load directed to the MariaDB nodes until the entire cluster is migrated.
Currently, migration from 8.0.x has been verified to work on a simple sysbench database workload.
For developers or those compiling from source, the following changes were relevant to this migration path:
SET GLOBAL innodb_fast_shutdown = 0;SELECT user, plugin FROM mysql.user WHERE plugin LIKE "%sha%";ALTER USER user_name IDENTIFIED WITH mysql_native_password BY 'new_password';SELECT table_schema, table_name FROM information_schema.COLUMNS
WHERE data_type="JSON";ALTER TABLE table_name MODIFY json_column LONGTEXT;CREATE TABLE `t1` (
`c1` int DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMPRESSION='lz4'SELECT table_schema, table_name, create_options FROM information_schema.TABLES WHERE
create_options LIKE "%ENCRYPT%";SELECT table_schema, table_name, create_options FROM information_schema.TABLES WHERE
create_options LIKE "%COMP%";-- MySQL: Creating a tablespace in a custom file location
mysql> CREATE TABLESPACE `ts1` ADD DATAFILE '/home/jan/galeradb/node1/ts1.ibd' Engine=InnoDB;
-- MySQL: Creating a table assigned to that tablespace
mysql> CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1;mysql> show create table t1;
| t1 | CREATE TABLE `t1` (
`c1` int NOT NULL,
PRIMARY KEY (`c1`)
) /*!50100 TABLESPACE `ts1` */ ENGINE=InnoDB ... |XA RECOVER; -- Should return an empty set-- Create user compatible with both engines
CREATE USER 'sst_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'strong_password';
GRANT ALL PRIVILEGES ON *.* TO 'sst_user'@'localhost';
FLUSH PRIVILEGES;Clean Data Directory: One way is to move all files under datadir to a new directory.
Install MariaDB: Install mariadb-server and mariadb-backup.
Required Settings: You must add these specific settings for the first node:
sst_user (and other system users) if mariadb-upgrade reports issues, as the mysql.user table structure is not fully compatible.mv /var/lib/mysql /var/lib/mysql_backup_timestamp
mkdir /var/lib/mysql
chown mysql:mysql /var/lib/mysqlSET GLOBAL innodb_fast_shutdown = 0;mysqladmin -u root -p shutdownmariadbd --help --verbose > /tmp/log 2>&1systemctl start mariadb[galera]
# ... standard galera settings ...
# 1. Point to the MariaDB Donor
# After the first MariaDB node has successfully joined, this variable
# should be set on all other nodes to the value of wsrep_node_name
# on the first MariaDB node.
wsrep_sst_donor=Name_of_First_MariaDB_Node
# 2. Use Binary SST
# For other joining nodes, mariabackup value should be used.
wsrep_sst_method=mariabackup
wsrep_sst_auth=sst_user:strong_password
wsrep_provider_options="gcs.check_appl_proto=0"[galera]
# ... standard galera settings ...
# 1. IGNORE PROTOCOL MISMATCH
# Required to avoid application protocol mismatch messages during migration.
wsrep_provider_options="gcs.check_appl_proto=0;gcache.size=2G"
# 2. USE LOGICAL SST (First Node Only)
# wsrep_sst_method should be set to mysqldump for the first MariaDB node
# to join the MySQL cluster.
wsrep_sst_method=mysqldump
# 3. SST AUTHENTICATION
# Should contain user and password and this user should exist on both
# MySQL and MariaDB databases with sufficient access rights.
wsrep_sst_auth=sst_user:strong_passwordOutdated page regarding migrating from MySQL to MariaDB Server. While potentially outdated, these resources may offer historical context or insights for specific scenarios.
Following compatibility report was done on 10.2.4 and may get some fixing in next minor releases
MySQL unix socket plugin can be different. MariaDB can get similar usage via INSTALL PLUGIN unix_socket SONAME 'auth_socket.so'; you may have to enable this plugin in config files via load plugin.
When using data type JSON , one should convert type to TEXT, virtual generated column works the same after.
When using InnoDB FULLTEXT index one should not use innodb_defragment
MySQL re-implemented partitioning in 5.7, thus you cannot perform in-place upgrades for partitioned tables. They will require mysqldump/import to work correctly in MariaDB.
This page is licensed: CC BY-SA / Gnu FDL
This section contains obsolete articles regarding migrating from MySQL to MariaDB Server. While potentially outdated, these resources may offer historical context or insights for specific scenarios.