MariaDB : Migration from MySQL to MariaDB

Deterministic guide for in-place upgrades and dump-and-restore migrations from MySQL 5.6 / 5.7 / 8.0 / 8.4 to MariaDB 10.6-LTS, 10.11-LTS, 11.x, 12.x. Covers the compatibility matrix, the four hard divergences (JSON, GTID, auth-plug-in, INVISIBLE vs IGNORED INDEX), the privilege-store migration (mysql.user to mysql.global_priv), and the mandatory mariadb-upgrade workflow.

Quick Reference

• MariaDB JSON is a LONGTEXT alias, NOT binary like MySQL 5.7.8+. After migration, ALWAYS add CHECK (JSON_VALID(col)) to every JSON column to preserve the MySQL validation invariant. Without it, a subsequent non-JSON UPDATE corrupts the row silently. (D-010, L-005)
• MariaDB GTID format is domain-server-sequence. MySQL GTID is uuid:seqno. They are INCOMPATIBLE. MySQL to MariaDB is a one-way dump-and-load, NOT a continuous GTID-tracked replication. (L-004)
• MySQL 8 default auth plug-in is caching_sha2_password. MariaDB does NOT ship it. ALWAYS re-create users with ed25519 or mysql_native_password before pointing apps at MariaDB.
• MariaDB uses ALTER TABLE t ALTER INDEX idx IGNORED. MySQL 8 uses INVISIBLE. Copying MySQL 8 syntax produces a syntax error. (L-006)
• ALWAYS run mariadb-upgrade exactly once after the binary swap. It migrates mysql.user to mysql.global_priv (10.4+) and runs CHECK TABLE / ALTER TABLE on format-drift. NEVER run it twice in a row : the second pass logs spurious warnings that mask real first-pass errors. (Vooronderzoek §6)
• NEVER copy a MySQL my.cnf verbatim. sql_mode defaults differ, query_cache_* was REMOVED in MariaDB 11.0+, default_authentication_plugin is unsupported, and several InnoDB variables have different default scaling.
• MySQL 5.6 is a near drop-in replacement for MariaDB 10.x (in-place upgrade works). MySQL 5.7+ requires JSON-validation remediation. MySQL 8.0+ requires user re-creation. MySQL 8.4 additionally removes the query cache (MariaDB also removed it in 11.0+).
• MariaDB has CREATE SEQUENCE + NEXT VALUE FOR (10.3+) that MySQL lacks. Migrating FROM MySQL : keep AUTO_INCREMENT as-is, NEVER auto-convert to sequences during migration. Convert deliberately after stability.
• Binary names changed in 10.5+ : mysqldump is now mariadb-dump, mysqlbinlog is mariadb-binlog. Old names remain as compatibility symlinks today, but cron jobs that hard-code mysqldump SHOULD be updated.
• Verify privileges after migration via SELECT user, host, plugin FROM mysql.global_priv; (10.4+), NOT only mysql.user. The mysql.user view is still queryable as a backward-compat layer but does not reflect role grants natively.

Decision Tree : Which Migration Path