> For the complete documentation index, see [llms.txt](https://mariadb.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mariadb.com/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator.md). # MySQL to MariaDB Migrator The MySQL to MariaDB Migrator automates end-to-end MySQL to MariaDB migrations — schema, data, users, and validation — in four selectable modes. {% hint style="info" %} **MariaDB tool.** The MySQL to MariaDB Migrator is proprietary MariaDB software, provided free to MariaDB customers and partners under approved usage terms. It is distributed from the [MariaDB community downloads page](https://mariadb.com/downloads/community/). {% endhint %} The **MySQL to MariaDB Migrator** is a MariaDB tool that automates end-to-end migrations from MySQL to MariaDB in a repeatable, auditable way. It orchestrates schema migration, data transfer, user and privilege migration, and post-migration validation, and it drives the standard MariaDB client tools (`mariadb-dump`, the `mariadb` client, and the `mariadb-mtk` data-transfer engine) under a single launcher. {% hint style="info" %} All four migration modes have been exercised end-to-end against representative source and target pairs, including AWS RDS sources and MariaDB Cloud targets. As with any migration, rehearse against a non-production target and validate the result before you migrate a production database. {% endhint %} The migrator complements the manual workflows in the [MySQL to MariaDB Migration: The Master Guide](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migration-the-master-guide.md): the Master Guide explains the migration paths and the compatibility considerations, while the migrator automates the dump, load, user-migration, and validation steps for you. ## Supported Versions * **Source:** MySQL 8.0 and 8.4 (some modes have version-specific requirements — see [Migration Modes](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migration-modes.md)). * **Target:** supported MariaDB Enterprise and Community editions. * **Accounts:** `caching_sha2_password` and `sha256_password` accounts are carried across with their existing password hashes intact, so application users do not need password resets after cutover. See [Application User Migration](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/application-user-migration.md). * **MariaDB Cloud** is validated as a target for the Offline Copy (`staged`), Parallel Restartable Streaming Copy (`two_step`), and Serial Streaming Copy (`one_step`) modes. * **Platforms:** the migrator is built and tested for Linux on x86-64 and ARM64, and for macOS on ARM64 (Apple silicon). macOS hosts require bash 4.4 or newer — see [Installation and First Run](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/installation-and-first-run.md#prerequisites). ## Migration Modes at a Glance The launcher presents four migration modes as a numbered menu. The internal identifier in parentheses is the canonical form used in configuration files, environment variables (`MODE=...`), and the command line (`--mode `). | Mode | Internal ID | Type | Best For | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------- | -------------------------------------------------------------------------------------------------------- | | [Serial Streaming Copy](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-serial-streaming-copy.md) | `one_step` | Offline | Smaller databases and standard maintenance windows | | [Parallel Restartable Streaming Copy](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-parallel-restartable-streaming-copy.md) | `two_step` | Offline | Larger datasets: loads tables concurrently, and splits large tables that have an `AUTO_INCREMENT` column | | [Offline Copy](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-offline-copy.md) | `staged` | Offline | Source and target not network-reachable, or a deferred / two-host load | | [Replication](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-replication.md) | `binlog` | Online | Low-downtime cutover with ongoing replication | Each mode links to its step-by-step guide above. For the variable-level detail on all four modes in one place, see [Migration Modes](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migration-modes.md). ## Choose a Guide If you are not sure which mode fits, match your situation to a guide: | Your situation | Guide | | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A small or medium database, a standard maintenance window is acceptable, and one host can reach both the source and the target | [Serial Streaming Copy](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-serial-streaming-copy.md) | | The source and target cannot reach each other (air-gapped or separate networks), or you want a checkpoint between the dump and the load | [Offline Copy](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-offline-copy.md) | | A large database where a single serial transfer is too slow, you can install the `mariadb-mtk` engine, and you can start from a clean target | [Parallel Restartable Streaming Copy](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-parallel-restartable-streaming-copy.md) | | Downtime must be minimal, the source uses `binlog_format=ROW` with no JSON columns, and you can perform a cutover | [Replication](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-replication.md) | If more than one row fits, use this order: minimal downtime points to Replication (when the source qualifies); otherwise, if one host cannot reach both sides, use Offline Copy; otherwise choose Serial Streaming Copy for a small or medium database and Parallel Restartable Streaming Copy for a large one. ## How the Tool Runs When launched interactively, the migrator first offers two top-level choices: * **Assess & Plan** — inspect the source and target, validate connectivity and compatibility, and produce an assessment report and a migration plan. No data is moved and nothing is written to the target. * **Assess + Run** — assess the source, then proceed to the full migration, with confirmation steps between phases. Preview a migration with **Assess & Plan** before committing to it; the assess and plan phases write their artifacts under `artifacts/` and leave the target untouched. ## AI-Assisted Operation via MCP The migrator can also be operated by an AI agent through the MariaDB Shell MCP server, which exposes tools to configure, plan, run, and resume a migration. {% hint style="info" %} **This ships separately.** The MCP plugin is not part of the MySQL to MariaDB Migrator and is not included in its release archive. It is installed through MariaDB Shell, is maintained independently, and requires an MCP-capable AI coding agent to drive it. The migrator has no dependency on either: the interactive launcher and the command-line interface work as documented on these pages without them. {% endhint %} Requirements: * A Linux or macOS host. The MCP path is not available on Windows. * The migrator installed, with `mariadb` and `mariadb-dump` on the `PATH`. * The plugin installed with `mariadb-shell -- mcp setup --installMigrator`, followed by a restart of the MCP server. The migrator tools register only when the server next starts, so an agent that reports no `migrator.*` tools needs the restart. * Both the source and the target registered as configured MCP connections. Two behaviors are worth knowing in advance: * Passwords can never be set in the configuration the agent writes. They are resolved from the MariaDB Shell secret store when the migration runs, so never put a password in a prompt. * A connection that cannot be authenticated does not produce an error. Password lookups use the full connection URI, host and port included, and a connection whose lookup fails is simply not offered as a data source. Specify the port on each connection. (Run directly, the launcher stops with a connection error instead.) For a full walkthrough, see the [MySQL to MariaDB migration tutorial](https://ai-plugins.mariadb.com/tutorials/mysql-to-mariadb-migration/). ## In This Section Start with the reference pages to understand how the tool installs, runs, and handles users: {% content-ref url="/pages/qi6FG7nU3phq7jrWsgFo" %} [Installation and First Run](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/installation-and-first-run.md) {% endcontent-ref %} {% content-ref url="/pages/MBIGDdfBjWcdMVHKgm42" %} [Migration Modes](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migration-modes.md) {% endcontent-ref %} {% content-ref url="/pages/vkxDtVFbdr7few6DazbB" %} [Application User Migration](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/application-user-migration.md) {% endcontent-ref %} {% content-ref url="/pages/k7L6kXrqus1dVZpfDa1U" %} [Environment Variables](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/environment-variables.md) {% endcontent-ref %} Then follow the step-by-step guide for your mode: {% content-ref url="/pages/UN5ErmbnyPpZCsoqGlfb" %} [Migrate with Serial Streaming Copy](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-serial-streaming-copy.md) {% endcontent-ref %} {% content-ref url="/pages/mGwua1Moo9xKKs9dFGLe" %} [Migrate with Offline Copy](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-offline-copy.md) {% endcontent-ref %} {% content-ref url="/pages/KbB0vYPtZApGttwVzbL1" %} [Migrate with Parallel Restartable Streaming Copy](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-parallel-restartable-streaming-copy.md) {% endcontent-ref %} {% content-ref url="/pages/SnWBE7bS9QIVv1ODzQnR" %} [Migrate with Replication](/docs/server/server-management/install-and-upgrade-mariadb/migrating-to-mariadb/moving-from-mysql/mysql-to-mariadb-migrator/migrate-with-replication.md) {% endcontent-ref %} ## Feedback Join the [MariaDB Community on Slack](https://r.mariadb.com/join-community-slack) to share your feedback. ## License The [MariaDB Software License Terms](https://legal.mariadb.com/agreements/enterprise/MariaDB_Software_License_Terms_2026-05-15.pdf) apply to all MariaDB Software unless otherwise stated. They do not alter the license terms of any free and open-source software (FOSS) or software subject to the Business Source License (BSL); see Section 7 of the MariaDB Software License Terms. For additional legal information, see the [MariaDB Terms](https://mariadb.com/terms/). ## See Also [An Easy Path from MySQL to MariaDB](https://mariadb.com/resources/blog/an-easy-path-from-mysql-to-mariadb-introducing-mariadb-migrator/) • blog post • 2026 • 4 minutes [Migrating from MySQL to MariaDB? Meet the MariaDB Migrator](https://youtu.be/fggPKN-upGI) • video • 2026 • 8 minutes *This page is licensed: CC BY-SA / Gnu FDL*