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.

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.

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.

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.

The migrator complements the manual workflows in the MySQL to MariaDB Migration: The Master Guide: 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).

• 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.

• 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.

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 <id>).

Mode	Internal ID	Type	Best For
Serial Streaming Copy	one_step	Offline	Smaller databases and standard maintenance windows
Parallel Restartable Streaming Copy	two_step	Offline	Larger datasets: loads tables concurrently, and splits large tables that have an AUTO_INCREMENT column
Offline Copy	staged	Offline	Source and target not network-reachable, or a deferred / two-host load
Replication	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.

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
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
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
Downtime must be minimal, the source uses binlog_format=ROW with no JSON columns, and you can perform a cutover	Replication

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.

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.

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.

In This Section

Start with the reference pages to understand how the tool installs, runs, and handles users:

Installation and First RunMigration ModesApplication User MigrationEnvironment Variables

Then follow the step-by-step guide for your mode:

Migrate with Serial Streaming CopyMigrate with Offline CopyMigrate with Parallel Restartable Streaming CopyMigrate with Replication

Feedback

Join the MariaDB Community on Slack to share your feedback.

License

The MariaDB Software License Terms 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.

See Also

An Easy Path from MySQL to MariaDB • blog post • 2026 • 4 minutes

Migrating from MySQL to MariaDB? Meet the MariaDB Migrator • video • 2026 • 8 minutes

_{This page is licensed: CC BY-SA / Gnu FDL}