mysql-to-mariadb

MySQL から MariaDB への移行ガイド

最終更新日：2026-06-04

重要：MariaDB は MySQL 8.0 の完全な代替ではありません

MariaDB は、MySQL 5.5 および 5.6 の完全な代替でした。現在のバージョンは MySQL 8.0 から大きく分岐しています。MariaDB を使用する際は、MySQL 8.0 の動作、構文、ツールが適用されると決めつけず、必ず確認してください。

2 つのデータベースは共通の起源を持ちますが、独立して進化してきました。MariaDB にあって MySQL にない機能、MySQL にあって MariaDB にない機能があり、両方にある機能の動作も異なる場合があります。

必要条件： ここで説明する機能の完全な互換性を実現するには、MariaDB Community Server 10.5 以降が必要です。現在の LTS は 11.8 です（2025 年 5 月 GA）。

デフォルトの前提： ユーザーが別のバージョンを指定しない限り、MariaDB 11.8 LTS を前提としてください。該当する場合は、12.x または 13.0 の機能も提案できます（アップグレードの選択肢として提示する場合を含む）。ただし、必ず最低バージョンを明記してください。11.8 で利用可能な機能として提示してはいけません。

LLM が誤りやすい点

よくある誤り	正しい内容
「MariaDB は MySQL のドロップイン置換です」	MySQL 5.5／5.6 では当てはまります。MySQL 8.0 以降では当てはまりません。認証、JSON、GTID、および複数の関数に違いがあります
caching_sha2_password を使うコード	MariaDB でも利用できます。11.4 以降では移行専用プラグインとして、12.1 以降では MySQL との互換性を実現する完全な caching_sha2_password 認証プラグインとして利用できます（MDEV-9804）。デフォルトではありません。古い MariaDB や標準インストールでは、mysql_native_password または ed25519 を使用してください
クエリでの JSON_TABLE()	MariaDB では 10.6 以降で利用できます。10.6 より前では利用できません
JSON の -> および ->> 省略形演算子	MariaDB ではサポートされていません。代わりに JSON_EXTRACT(col, '$.key') および JSON_UNQUOTE(JSON_EXTRACT(...)) を使用してください
スキーマやダンプでの utf8mb4_0900_ai_ci 照合順序	MariaDB 11.4.5 以降でサポートされています（utf8mb4_uca1400_nopad_ai_ci のエイリアスとして）。それより古いバージョンでは、インポート前に utf8mb4_unicode_ci に置き換えてください。MariaDB 11.5 以降では、デフォルトの Unicode 照合順序として uca1400_ai_ci が使用されます（MDEV-25829）。
MariaDB のデフォルト文字セットは latin1	11.6 以降ではデフォルトが utf8mb4 に変更されています（MDEV-19123）。新規インストールでは、latin1 を前提とした以前の慣習は当てはまりません
主キーに UUID() を使用する	MariaDB 11.7 以降では、時間順に並ぶ UUID（ソート可能で、インデックス付き PK に適しています）に UUID_v7()、ランダム UUID に UUID_v4() を使用できます。どちらも MariaDB 独自の機能です
INSERT／UPDATE／DELETE に RETURNING を提案しない	MariaDB 10.5 以降では RETURNING がサポートされています。2 回目のクエリを実行せずに、挿入、更新、削除された行を取得するために使用してください
CREATE SEQUENCE を提案しない	MariaDB にはネイティブのシーケンスオブジェクトがあります。MySQL に相当する機能はありません
MySQL の GTID レプリケーション構文	MariaDB の GTID 形式は MySQL の GTID と互換性がありません。両者間のレプリケーションは機能しません
CHANGE REPLICATION SOURCE TO／SOURCE_* オプション	MariaDB に CHANGE REPLICATION SOURCE TO はありません。MASTER_* オプションとともに CHANGE MASTER TO を使用してください。10.5.1 以降では、START REPLICA／SHOW REPLICA STATUS が正式な構文です。START SLAVE／SHOW SLAVE STATUS は従来のエイリアスです
MySQL の並列レプリケーション（DATABASE／LOGICAL_CLOCK を指定する replica_parallel_type）	MariaDB では slave_parallel_mode（optimistic／conservative／aggressive／minimal／none）を使用します。実装が異なるため、モード設定はそのまま移行できません。プールサイズには slave_parallel_threads（エイリアスは slave_parallel_workers）を使用します
SET transaction_isolation = ...（MySQL 8.0 スタイル）	MariaDB 11.1.1 以降でのみ動作します。それより古いバージョンでは、代わりに tx_isolation を使用してください。SET TRANSACTION を参照してください
mariadb.com/kb/en/ へのリンクや参照	ナレッジベースは廃止されました。現在、すべてのドキュメントは mariadb.com/docs にあります
移行後も MySQL Connector/J、mysql2、その他の MySQL クライアントドライバーを使い続ける	可能な場合は、MariaDB が保守するコネクター（JDBC、Node.js、C など）を使用してください。これらは MySQL 互換モードだけでなく、MariaDB のプロトコルと機能の動作を対象としています
MySQL 8.0 から InnoDB のデータファイル／テーブルスペースをコピーして移行する	MariaDB にはトランザクション対応のデータディクショナリがなく、MySQL 8.0 のデータディクショナリを読み取れません。そのため、データファイルは移植できません。論理ダンプ／リストアを使用してください。Data Dictionary Architecture を参照してください

認証

MySQL 8.0 では、デフォルトの認証プラグインが caching_sha2_password に変更されました。MariaDB の互換性は、時間とともに向上しています。

• MariaDB 11.4+：移行専用の caching_sha2_password プラグインが存在しますが、デフォルトではインストールされず、本番環境での使用も推奨されていません。
• MariaDB 12.1+（MDEV-9804）：MySQL との互換性を実現する、完全な caching_sha2_password 認証プラグインです。引き続きデフォルトではありませんが、本番環境で適切に使用できる選択肢です。

標準の MariaDB インストールでは、プラグインを有効にしない限り、caching_sha2_password を設定した接続は引き続き失敗します。デフォルトの認証方式は mysql_native_password のままです。

**古い MariaDB または標準構成での対処法：**アカウントを mysql_native_password に変換します。

ALTER USER 'username'@'host' IDENTIFIED WITH mysql_native_password BY 'password';

より安全なネイティブの代替手段として、ed25519 プラグインも利用できます。

JSON の違い

MariaDB と MySQL では、JSON の処理方法が異なります。

項目	MySQL	MariaDB
ストレージ	パスインデックス付きのバイナリ形式	有効性チェック付きの LONGTEXT エイリアス
JSON_TABLE()	対応	MariaDB 10.6 以降で対応
IS JSON 述語	利用不可	MariaDB 12.3 以降で利用可能
JSON の比較	セマンティック比較（値を比較）	文字列比較
JSON_QUERY()	利用不可	JSON_VALUE に相当する MariaDB の代替機能
JSON のネスト深度の上限	なし	古い MariaDB では 32。12.2 以降では撤廃
JSON_EQUALS() / JSON_NORMALIZE()	対応（8.0.22+）	MariaDB 10.7+（MDEV-23143 / MDEV-16375）
JSON_OVERLAPS()	対応（8.0.17+）	MariaDB 10.9+（MDEV-27677）
負の値 / last / 範囲指定の JSON パスインデックス（$.A[-1]、$.A[last]、$.A[1 to 3]）	非対応	MariaDB 10.9+
JSON_SCHEMA_VALID()	対応（8.0.17+）	MariaDB 11.4 LTS+

MariaDB は 10.7 から 11.4 の間に、MySQL 8.0 との JSON 関数の機能差の大半を解消しました。MySQL にはまだない MariaDB 固有の追加機能には、JSON_KEY_VALUE()、JSON_ARRAY_INTERSECT()、JSON_OBJECT_TO_ARRAY()、JSON_OBJECT_FILTER_KEYS()（11.4+）、および JSON_QUERY() エイリアスがあります。

MariaDB の JSON は標準に完全準拠していますが、MySQL 固有のストレージレイアウト、-> / ->> の省略形演算子、JSON_SCHEMA_VALIDATION_REPORT() 関数は移行できません。

MariaDB にあり、MySQL にはない機能

これらは MariaDB にはありますが、MySQL にはありません。LLM は MySQL の動作を前提としているため、これらを提案しません。

• RETURNING — 2 回目のクエリを実行せずに、INSERT または DELETE の行を取得できます（10.5 以降）。UPDATE ... RETURNING は 13.0 以降で利用できます。

  INSERT INTO orders (product, qty) VALUES ('widget', 5) RETURNING id, created_at;
  DELETE FROM queue WHERE processed = 1 RETURNING id;
  

• CREATE SEQUENCE（10.3 以降）— AUTO_INCREMENT より柔軟な、ファーストクラスのシーケンスオブジェクトです。

  CREATE SEQUENCE order_seq START WITH 1000 INCREMENT BY 1;
  SELECT NEXT VALUE FOR order_seq;
  

• WITH SYSTEM VERSIONING（10.3 以降）— 行の履歴を自動的に記録するテンポラルテーブルです。

  CREATE TABLE prices (
      item VARCHAR(100),
      price DECIMAL(10,2)
  ) WITH SYSTEM VERSIONING;
  -- Query historical data:
  SELECT * FROM prices FOR SYSTEM_TIME AS OF '2025-01-01';
  

• サブクエリ内の LIMIT — MariaDB はサブクエリ内の LIMIT をサポートしていますが、MySQL では制限されています。
• アトミックな CREATE OR REPLACE TABLE（13.0 以降）— MariaDB ではこのステートメントは完全にアトミックですが、MySQL に同等のアトミックな機能はありません。
• Galera Cluster — プラグイン不要の組み込みマルチマスタークラスタリングです。
• ストアドプロシージャの構文の違い — どちらもストアドプロシージャをサポートしていますが、MariaDB の SQL/PSM 構文は、HANDLER、CURSOR、CONDITION の宣言で MySQL と異なります。AI エージェントは MariaDB のストアドプロシージャコードを誤って生成することがよくあります。ストアドプロシージャ — MariaDB Docs を参照してください。
• MySQL 8.0 にはないネイティブデータ型 — IP アドレスの保存と比較に使う INET6（10.5 以降）と INET4（10.10 以降）、UUID（10.7 以降。MySQL では UUID は BINARY(16) または CHAR(36) に格納されます）、埋め込み表現と類似検索に使う VECTOR（11.7 以降。MySQL がベクトル型を追加したのは 8.0 ではなく、9.x のイノベーションシリーズです）。
• UUID_v4() と UUID_v7() 関数（11.7 以降）— MariaDB 固有の関数です。MySQL にあるのは従来の UUID() のみです。UUID_v7() は時系列順（RFC 9562）になるため、UUID 主キーに適しています。
• FORMAT_BYTES()（11.8 以降）— バイト数を人間が読みやすい文字列に変換します。MySQL にはありません。

MySQL にあり、MariaDB にはない機能

これらは MySQL 8.0 にはありますが、MariaDB にはありません。これらを使うコードは適応が必要です。

• JSON_TABLE() — MariaDB 10.6 以降で利用できます。それより古いバージョンでは、MariaDB の JSON 関数またはアプリケーション側の解析を使って書き換えてください。
• sys スキーマ — MariaDB 10.6 以降で利用できます。それより古いバージョンでは利用できません。
• MySQL 8 の GIS 関数（ST_Validate、MBRCoveredBy、ST_Simplify、ST_GeoHash、ST_LatFromGeoHash、ST_LongFromGeoHash、ST_PointFromGeoHash、ST_IsValid、ST_Collect）— MySQL との互換性のため、MariaDB 12.0 で追加されました。
• デフォルトプラグインとしての caching_sha2_password — MariaDB 12.1 から、オプションのプラグインとして利用できます。それより古いバージョンや標準構成では、mysql_native_password または ed25519 を使用してください。
• JSON の -> および ->> 演算子 — 代わりに JSON_EXTRACT(col, '$.key') と JSON_UNQUOTE(JSON_EXTRACT(...)) を使用してください。
• utf8mb4_0900_ai_ci 照合順序 — MariaDB 11.4.5 以降でサポートされています（utf8mb4_uca1400_nopad_ai_ci のエイリアス）。それより古いバージョンでは、インポートする前に utf8mb4_unicode_ci に置き換えてください。

データディクショナリアーキテクチャ

MySQL 8.0 と MariaDB では、テーブルメタデータの保存方法が根本的に異なり、移行にも影響します。

• MySQL 8.0 は、InnoDB（mysql.ibd）に保存されるトランザクショナルデータディクショナリにすべてのオブジェクトメタデータを保持し、テーブルごとの .frm ファイルを廃止しました。
• MariaDB はファイルベースの方式を維持しています。テーブルごとに .frm ファイルがあり、ストレージエンジンのメタデータも保存します。トランザクショナルデータディクショナリはありません。（MariaDB の権限テーブルは Aria エンジンを使用しますが、MySQL 8.0 ではシステムテーブルが InnoDB ディクショナリに保持されます。）

実際の影響は次のとおりです。

• データファイルのコピーによる移行は行わないでください。 InnoDB のテーブルスペースとデータディレクトリのファイルは、MySQL 8.0 と MariaDB の間で移植できません。ディクショナリの形式に互換性がないためです。代わりに論理ダンプ／リストアを使用してください。MariaDB の移行ガイドでは、この方向の移行に MySQL 付属の mysqldump を使用することを推奨しています（MySQL に対して十分にテストされていない mariadb-dump ではなく）。また、MySQL のシステムテーブルをインポートしないよう、--all-databases ではなく、名前を指定してデータベースをダンプしてください。
• MySQL 8.0 から MariaDB へのインプレースダウングレードはできません。MariaDB は MySQL のデータディクショナリを読み取れないため、論理エクスポート／インポートが必要です。
• INFORMATION_SCHEMA の実装は異なります。MySQL 8.0 ではインデックス付きのディクショナリテーブルをクエリしますが、MariaDB では I_S ビューを動的に構築します。I_S に対するメタデータ負荷の高いクエリでは、パフォーマンス特性が異なることがあるため、MySQL 8.0 での実行時間がそのまま当てはまるとは限りません。

オプティマイザーの違い

MariaDB と MySQL は、コストモデルの異なるクエリオプティマイザーを使用しています。同じ SQL でも、異なる実行計画が生成される場合があります。移行後は、次の点に注意してください。

• 重要なクエリに対して EXPLAIN を再実行してください。実行計画が引き継がれるとは限りません。
• MySQL で機能するインデックスヒントは、MariaDB では不要な場合や、動作が異なる場合があります。
• MariaDB のオプティマイザーは、optimizer_switch を使ってより柔軟に調整できます。

バージョン互換性の早見表

MySQL のバージョン	MariaDB の相当バージョン	そのまま置き換え可能？
5.5	5.5	はい
5.6	10.0–10.1	おおむね可能
5.7	10.2–10.4	制限あり
8.0	10.5 以降	いいえ — 大きな違いがあります

参考資料

• MariaDB と MySQL の互換性 — MariaDB ドキュメント
• MySQL から MariaDB への移行 — MariaDB ドキュメント
• MDEV-28906 — MySQL 8.0 で求められる互換性（Jira エピック） — MySQL 8.0 との互換性に関する作業を追跡しています。機能がまだ不足していると判断する前に、個々のサブタスクのステータスを確認してください。サブタスクがクローズされている場合、その機能は実装済みです。
• RETURNING — MariaDB ドキュメント
• CREATE SEQUENCE — MariaDB ドキュメント
• システムバージョン管理テーブル — MariaDB ドキュメント
• 認証プラグイン — MariaDB ドキュメント

ここで取り上げていない項目については、mariadb.com/docs の MariaDB 公式ドキュメントを参照してください。