mariadb-migrator
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 co
SKILL.mdcodex/dev-plugin/skills/mariadb-migrator/SKILL.md
GitHubMySQL → 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
outat a directory that already holds astate.jsonfrom an earlier run, the new run reports every stepSKIPPED, exits 0, and migrates nothing. Omitoutfor every new migration (a freshartifacts/<command>_<mode>_<timestamp>is chosen for you) and pass it only tomigrator.resume. And never trustsucceededalone — check that every step in the report saysDONE.
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.jsonand 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 withmariadb-shell -- mcp setup --installMigrator. This takes effect on the next server start, not the current one; if you cannot seemigrator.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_connectionsand build the configuration out of what it returns. Do not invent a host: it will be refused. - The
mariadbclient andmariadb-dumpmust be on the server'sPATH, andpvshould be (seemariadb-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. Use127.0.0.1. This compounds with the port rule inmariadb-migrator-configure:localhost:3307both looks configured and loses the port from the secret-store lookup. - The client option files must be clean. A
verboseorverticalline in~/.my.cnfor/etc/my.cnf.d/*corrupts the single-value captures the phase scripts rely on. The tooling probes for this with--print-defaultsbefore 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 refusedset_config. planbefore everyrun, including after amerge=Trueedit.- Use
merge=Truefor 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— writingconfig/migration.yamlwithmigrator.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.