mariadb-impl-migration-mysql-to-mariadb

name	mariadb-impl-migration-mysql-to-mariadb
description	Use when migrating a MySQL instance to MariaDB, comparing compatibility per MySQL version, identifying syntax divergences, planning replication bridging, re-validating JSON data after the binary swap, or running mariadb-upgrade to finalise the migration. Prevents the common mistake of expecting GTID continuity (incompatible per L-004), assuming JSON storage is the same (LONGTEXT-alias per L-005 and D-010), copying MySQL 8 INVISIBLE INDEX syntax (MariaDB uses IGNORED per L-006), keeping caching_sha2_password users (no MariaDB plug-in), skipping mariadb-upgrade after the binary swap, or copying my.cnf verbatim across the divide. Covers per-MySQL-version compatibility matrix (5.6 / 5.7 / 8.0 / 8.4), JSON storage divergence and CHECK (JSON_VALID(col)) remediation, GTID-format divergence (one-way dump-and-load only), authentication-plugin shift, mysql.user vs mysql.global_priv (10.4+), sql_mode default differences, role syntax differences, MariaDB sequence syntax (10.3+), INVISIBLE vs IGNORED INDEX rename, the mariadb-upgrade workflow, and end-to-end migration steps (in-place upgrade vs dump-and-restore). Keywords: migration, MySQL to MariaDB, drop-in compatibility, JSON divergence, JSON_VALID, CHECK constraint, GTID incompatible, domain-server-sequence, mysql.user, mysql.global_priv, mariadb-upgrade, mysql_upgrade, caching_sha2_password, ed25519, mysql_native_password, INSTALL SONAME auth_ed25519, role syntax, SET DEFAULT ROLE, sequence syntax, CREATE SEQUENCE, NEXT VALUE FOR, AUTO_INCREMENT, sql_mode default, STRICT_TRANS_TABLES, INVISIBLE INDEX, IGNORED INDEX, query cache removed 11.0, my.cnf, mariadb-dump, mysqldump rename, how do I migrate from MySQL, can mariadb replicate to mysql, can mysql connect to mariadb, replication broken after upgrade, why does INVISIBLE INDEX fail, why does caching_sha2_password fail, my JSON column got corrupted after migration
license	MIT
compatibility	Designed for Claude Code. Requires MariaDB 10.6-LTS, 10.11-LTS, 11.x, 12.x.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

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 SHOULD be updated.