MySQL → MariaDB Migration — Overview
The MySQL-to-MariaDB Migrator is a standalone program (a Python orchestrator
driving a directory of POSIX shell scripts) that copies databases from a MySQL
source to a MariaDB target. The migrator.* tools of the mariadb-shell MCP
server configure and drive it: you write its config/migration.yaml, then run
one of its modes and read its report.
This skill is the map. Read the focused sub-skill for the step you are on.
Two things are deliberately NOT yours to choose, and both are enforced by
refusing the configuration rather than by failing later:
- Only servers that are already configured MCP connections may be named.
- You can never set a password. Each is read from the shell's secret store
at the moment a migration runs.
Get the configuration right first — a wrong one is refused, and a plausible but
incomplete one produces a failed run deep in the dump step.
The one rule that silently produces a false success: the orchestrator is
resume-safe. If you point out at a directory that already holds a
state.json from an earlier run, the new run reports every step SKIPPED,
exits 0, and migrates nothing. Omit out for every new migration (a fresh
artifacts/<command>_<mode>_<timestamp> is chosen for you) and pass it only to
migrator.resume. And never trust succeeded alone — check that every step in
the report says DONE.
What LLMs Often Miss
The whole migration is driven by MCP tool calls, never from the shell. The
migrator.* tools perform the migration; the db.* tools — db.list_connections,
db.connect, db.list_schemas, db.list_objects, db.get_object_details,
db.execute_sql — are how you look at either server. Do not use the Bash tool
to invoke mariadb, mysql, mariadb-dump, mysqldump, mariadb-import,
mariadb-mtk or mariadb-shell itself — not to dump, not to load, not to run
a single SELECT, not to read a version, and not to "just quickly check"
something.
| If you reach for… |
…call this instead |
mysqldump/mariadb-dump piped into a client, to move the data |
migrator.run — that pipeline is mode 1 |
mariadb -e 'SELECT ...' for row counts or a spot-check |
db.execute_sql on the target connection |
mariadb -e 'SHOW DATABASES' / SHOW TABLES to see what is there |
db.list_schemas, db.list_objects |
mariadb -e 'SHOW CREATE TABLE' to check a definition or a foreign key |
db.get_object_details |
mariadb --version, or a client call to read VERSION() |
db.connect + db.execute_sql on the configured connection |
mariadb-mtk by hand for a faster load |
mode 2 (two_step) with SQLINESDATA_BIN set — see mariadb-migrator-modes |
mariadb-shell on the command line |
the MCP tools it already exposes; the CLI is for the operator, not for you |
ls/cat/find to locate the install or its config |
the config path migrator.set_config returns, and the install_dir a run returns |
zcat/grep over a dump to count objects |
nothing — report that no independent source count was available (mariadb-migrator-modes) |
Three reasons the shell path cannot work, not merely shouldn't:
- You do not have the passwords, and must not ask for them. They stay in the
shell's secret store and are resolved inside the server process at the moment a
run starts, so a hand-built command line has no credential to offer.
- Anything done outside the orchestrator is invisible to it.
state.json,
report.json and the per-step statuses are what "the migration succeeded" is
judged from, and a hand-run step appears in none of them.
- Every shell command is separately approval-gated, so guessing at a command
line turns one tool call into a string of prompts.
Two narrow exceptions, and they are the only shell commands these skills ever
ask for: command -v mariadb-mtk, to learn whether that binary exists at all
(mariadb-migrator-modes), and checking a mode 3 dump against its SHA-256
manifest on disk. Both look at the machine, not at a database. Nothing else.
The workflow
0. discover connections, schemas, and what was asked → mariadb-migrator-discovery
│
▼
1. choose the mode → mariadb-migrator-modes
│
▼
2. write config/migration.yaml (set_config) → mariadb-migrator-configure
│
▼
3. plan, then run — or resume a failed run → mariadb-migrator-run
│
▼
4. verify on the target, then report the result → mariadb-migrator-verify
anything refused, failed, or defect-shaped → mariadb-migrator-troubleshooting
Preconditions
- The tooling must be installed, or the
migrator.* tools are not registered
at all — a server with no install advertises none of them rather than four
tools whose every call would fail. Install with
mariadb-shell -- mcp setup --installMigrator. This takes effect on the next
server start, not the current one; if you cannot see migrator.set_config,
that is why.
- Not available on Windows. The tooling is a POSIX shell program.
- Both servers must be configured connections. Start by calling
db.list_connections and build the configuration out of what it returns. Do
not invent a host: it will be refused.
- The
mariadb client and mariadb-dump must be on the server's PATH, and
pv should be (see mariadb-migrator-troubleshooting).
- Never name a host
localhost. The MySQL/MariaDB C client reads it as "use
the Unix socket" and ignores the port entirely, so a source on any other port
is silently contacted on the wrong instance — or not at all. Use 127.0.0.1.
This compounds with the port rule in mariadb-migrator-configure:
localhost:3307 both looks configured and loses the port from the
secret-store lookup.
- The client option files must be clean. A
verbose or vertical line in
~/.my.cnf or /etc/my.cnf.d/* corrupts the single-value captures the phase
scripts rely on. The tooling probes for this with --print-defaults before
running any query; fix the option file rather than looking for a bypass.
The four tools
| Tool |
Purpose |
migrator.set_config(mode, env, merge=False) |
Write config/migration.yaml. Returns the path, the keys, the example's path, and which connection each account resolved to. |
migrator.plan(mode, out=None, timeout=3600) |
Resolve the step list for a mode and validate the configuration. Executes nothing and needs no reachable server. |
migrator.run(mode, out=None, timeout=3600) |
Perform the migration. Changes the target, and in some modes the source. |
migrator.resume(mode, out, timeout=3600) |
Continue a failed run from the state.json in that run's out directory. out is required here. |
out is always relative to the install directory (an absolute path is
refused). Every invocation gets a closed stdin, so an incomplete configuration
fails saying what is missing instead of hanging on a prompt.
The modes at a glance
This is the short version to show an operator who has to choose. The full table,
the per-mode gates and the mode-specific traps are in
mariadb-migrator-modes — read it before configuring.
| # |
Mode id |
Called |
Type |
The tradeoff in one line |
| 1 |
one_step |
Serial Streaming Copy |
offline |
Simplest and most predictable — the default recommendation. |
| 2 |
two_step |
Parallel Restartable Streaming Copy |
offline |
Faster on large databases, but needs mariadb-mtk, which is not bundled. |
| 3 |
staged |
Offline Copy |
offline |
Dumps to disk with checksums first, loads separately; needs bash 4. |
| 4 |
binlog |
Replication |
online |
Low-downtime cutover; needs a MySQL 8.0+ source and no JSON columns. |
inplace and replace_slave also exist. Do not pick them — see
mariadb-migrator-modes.
Guidelines
- Build the configuration from
db.list_connections, never from what the user
typed. A host they name that is not configured cannot be migrated to or
from, and saying so early is more useful than a refused set_config.
plan before every run, including after a merge=True edit.
- Use
merge=True for a correction, not a fresh full write — you keep the
keys you got right, and the merged result is validated as a whole anyway.
- Report what the report says. If a step failed, name the step and quote from
its
output_tail; the tooling's own diagnosis is almost always the answer.
- Modes 1, 2 and 3 are offline: the source is read, not changed, but the
target is written. Mode 4 leaves replication running. Never run any of them
against a production target without the user's explicit go-ahead.
See Also
mariadb-migrator-discovery — starting from a bare request: what to probe, show and ask.
mariadb-migrator-modes — the mode reference and each mode's own gates.
mariadb-migrator-configure — writing config/migration.yaml with migrator.set_config.
mariadb-migrator-run — plan, run, resume, and checking a run three ways.
mariadb-migrator-verify — verifying on the target and reporting the result.
mariadb-migrator-troubleshooting — known defects and the failure playbook.
mariadb-schema-management — versioned schema lifecycle, for a schema that
will keep evolving after it has been migrated.
mariadb-schema-create-script — authoring a single MariaDB create script.
mysql-to-mariadb — MySQL/MariaDB dialect and feature differences, for fixing
up SQL that the migration carried across verbatim.
1---2name: mariadb-migrator3description: "Overview and entry point for migrating a MySQL database to MariaDB with the migrator.* tools of the mariadb-shell MCP server — what the tooling is, the two things you may never choose (unconfigured connections, passwords), the resume-safe trap that reports success while migrating nothing, the four tools, and the discover → mode → configure → run → verify workflow. Use when asked to migrate/move/port a MySQL database or schema to MariaDB, when asked to migrate from MySQL (target may be left unstated — assume MariaDB), to configure or run the MySQL-to-MariaDB migration tooling, or when a migration run failed and has to be diagnosed or resumed; then read the focused sub-skill for the step you are on."4metadata:5 source: https://skillmd.com/skills/mariadb-corporation/mariadb-migrator6---78# MySQL → MariaDB Migration — Overview910The **MySQL-to-MariaDB Migrator** is a standalone program (a Python orchestrator11driving a directory of POSIX shell scripts) that copies databases from a MySQL12source to a MariaDB target. The `migrator.*` tools of the **`mariadb-shell` MCP13server** configure and drive it: you write its `config/migration.yaml`, then run14one of its modes and read its report.1516This skill is the map. Read the focused sub-skill for the step you are on.1718**Two things are deliberately NOT yours to choose**, and both are enforced by19refusing the configuration rather than by failing later:20211. **Only servers that are already configured MCP connections may be named.**222. **You can never set a password.** Each is read from the shell's secret store23 at the moment a migration runs.2425Get the configuration right first — a wrong one is refused, and a *plausible but26incomplete* one produces a failed run deep in the dump step.2728> **The one rule that silently produces a false success:** the orchestrator is29> **resume-safe**. If you point `out` at a directory that already holds a30> `state.json` from an earlier run, the new run reports every step `SKIPPED`,31> **exits 0, and migrates nothing**. Omit `out` for every new migration (a fresh32> `artifacts/<command>_<mode>_<timestamp>` is chosen for you) and pass it only to33> `migrator.resume`. And never trust `succeeded` alone — check that every step in34> the report says `DONE`.3536## What LLMs Often Miss3738**The whole migration is driven by MCP tool calls, never from the shell.** The39`migrator.*` tools perform the migration; the `db.*` tools — `db.list_connections`,40`db.connect`, `db.list_schemas`, `db.list_objects`, `db.get_object_details`,41`db.execute_sql` — are how you look at either server. **Do not use the Bash tool42to invoke `mariadb`, `mysql`, `mariadb-dump`, `mysqldump`, `mariadb-import`,43`mariadb-mtk` or `mariadb-shell` itself** — not to dump, not to load, not to run44a single `SELECT`, not to read a version, and not to "just quickly check"45something.4647| If you reach for… | …call this instead |48| --- | --- |49| `mysqldump`/`mariadb-dump` piped into a client, to move the data | `migrator.run` — that pipeline *is* mode 1 |50| `mariadb -e 'SELECT ...'` for row counts or a spot-check | `db.execute_sql` on the target connection |51| `mariadb -e 'SHOW DATABASES'` / `SHOW TABLES` to see what is there | `db.list_schemas`, `db.list_objects` |52| `mariadb -e 'SHOW CREATE TABLE'` to check a definition or a foreign key | `db.get_object_details` |53| `mariadb --version`, or a client call to read `VERSION()` | `db.connect` + `db.execute_sql` on the configured connection |54| `mariadb-mtk` by hand for a faster load | mode 2 (`two_step`) with `SQLINESDATA_BIN` set — see `mariadb-migrator-modes` |55| `mariadb-shell` on the command line | the MCP tools it already exposes; the CLI is for the operator, not for you |56| `ls`/`cat`/`find` to locate the install or its config | the config path `migrator.set_config` returns, and the `install_dir` a run returns |57| `zcat`/`grep` over a dump to count objects | nothing — report that no independent source count was available (`mariadb-migrator-modes`) |5859Three reasons the shell path cannot work, not merely shouldn't:6061- **You do not have the passwords, and must not ask for them.** They stay in the62 shell's secret store and are resolved inside the server process at the moment a63 run starts, so a hand-built command line has no credential to offer.64- **Anything done outside the orchestrator is invisible to it.** `state.json`,65 `report.json` and the per-step statuses are what "the migration succeeded" is66 judged from, and a hand-run step appears in none of them.67- **Every shell command is separately approval-gated**, so guessing at a command68 line turns one tool call into a string of prompts.6970**Two narrow exceptions, and they are the only shell commands these skills ever71ask for:** `command -v mariadb-mtk`, to learn whether that binary exists at all72(`mariadb-migrator-modes`), and checking a mode 3 dump against its SHA-25673manifest on disk. Both look at the *machine*, not at a database. Nothing else.7475## The workflow7677```text780. discover connections, schemas, and what was asked → mariadb-migrator-discovery79 │80 ▼811. choose the mode → mariadb-migrator-modes82 │83 ▼842. write config/migration.yaml (set_config) → mariadb-migrator-configure85 │86 ▼873. plan, then run — or resume a failed run → mariadb-migrator-run88 │89 ▼904. verify on the target, then report the result → mariadb-migrator-verify9192 anything refused, failed, or defect-shaped → mariadb-migrator-troubleshooting93```9495## Preconditions9697- **The tooling must be installed**, or the `migrator.*` tools are not registered98 at all — a server with no install advertises none of them rather than four99 tools whose every call would fail. Install with100 `mariadb-shell -- mcp setup --installMigrator`. **This takes effect on the next101 server start, not the current one**; if you cannot see `migrator.set_config`,102 that is why.103- **Not available on Windows.** The tooling is a POSIX shell program.104- **Both servers must be configured connections.** Start by calling105 `db.list_connections` and build the configuration out of what it returns. Do106 not invent a host: it will be refused.107- The `mariadb` client and `mariadb-dump` must be on the server's `PATH`, and108 **`pv` should be** (see `mariadb-migrator-troubleshooting`).109- **Never name a host `localhost`.** The MySQL/MariaDB C client reads it as "use110 the Unix socket" and ignores the port entirely, so a source on any other port111 is silently contacted on the wrong instance — or not at all. Use `127.0.0.1`.112 This compounds with the port rule in `mariadb-migrator-configure`:113 `localhost:3307` both looks configured and loses the port from the114 secret-store lookup.115- **The client option files must be clean.** A `verbose` or `vertical` line in116 `~/.my.cnf` or `/etc/my.cnf.d/*` corrupts the single-value captures the phase117 scripts rely on. The tooling probes for this with `--print-defaults` before118 running any query; fix the option file rather than looking for a bypass.119120## The four tools121122| Tool | Purpose |123| --- | --- |124| `migrator.set_config(mode, env, merge=False)` | Write `config/migration.yaml`. Returns the path, the keys, the example's path, and which connection each account resolved to. |125| `migrator.plan(mode, out=None, timeout=3600)` | Resolve the step list for a mode and validate the configuration. **Executes nothing** and needs no reachable server. |126| `migrator.run(mode, out=None, timeout=3600)` | Perform the migration. **Changes the target**, and in some modes the source. |127| `migrator.resume(mode, out, timeout=3600)` | Continue a failed run from the `state.json` in that run's `out` directory. `out` is required here. |128129`out` is always **relative to the install directory** (an absolute path is130refused). Every invocation gets a closed stdin, so an incomplete configuration131fails saying what is missing instead of hanging on a prompt.132133## The modes at a glance134135This is the short version to show an operator who has to choose. The full table,136the per-mode gates and the mode-specific traps are in137`mariadb-migrator-modes` — read it before configuring.138139| # | Mode id | Called | Type | The tradeoff in one line |140| --- | --- | --- | --- | --- |141| 1 | `one_step` | Serial Streaming Copy | offline | Simplest and most predictable — **the default recommendation**. |142| 2 | `two_step` | Parallel Restartable Streaming Copy | offline | Faster on large databases, but needs `mariadb-mtk`, which is not bundled. |143| 3 | `staged` | Offline Copy | offline | Dumps to disk with checksums first, loads separately; needs bash 4. |144| 4 | `binlog` | Replication | online | Low-downtime cutover; needs a MySQL 8.0+ source and **no `JSON` columns**. |145146`inplace` and `replace_slave` also exist. **Do not pick them** — see147`mariadb-migrator-modes`.148149## Guidelines150151- **Build the configuration from `db.list_connections`, never from what the user152 typed.** A host they name that is not configured cannot be migrated to or153 from, and saying so early is more useful than a refused `set_config`.154- **`plan` before every `run`**, including after a `merge=True` edit.155- **Use `merge=True` for a correction**, not a fresh full write — you keep the156 keys you got right, and the merged result is validated as a whole anyway.157- **Report what the report says.** If a step failed, name the step and quote from158 its `output_tail`; the tooling's own diagnosis is almost always the answer.159- Modes 1, 2 and 3 are **offline**: the source is read, not changed, but the160 target is written. Mode 4 leaves replication running. Never run any of them161 against a production target without the user's explicit go-ahead.162163## See Also164165- `mariadb-migrator-discovery` — starting from a bare request: what to probe, show and ask.166- `mariadb-migrator-modes` — the mode reference and each mode's own gates.167- `mariadb-migrator-configure` — writing `config/migration.yaml` with `migrator.set_config`.168- `mariadb-migrator-run` — `plan`, `run`, `resume`, and checking a run three ways.169- `mariadb-migrator-verify` — verifying on the target and reporting the result.170- `mariadb-migrator-troubleshooting` — known defects and the failure playbook.171- `mariadb-schema-management` — versioned schema lifecycle, for a schema that172 will keep evolving after it has been migrated.173- `mariadb-schema-create-script` — authoring a single MariaDB create script.174- `mysql-to-mariadb` — MySQL/MariaDB dialect and feature differences, for fixing175 up SQL that the migration carried across verbatim.