Convert MariaDB Tables Safely with mariadb-convert-table-format

You will finish with a controlled way to convert one or more MariaDB tables to a chosen storage engine, then verify the engine reported by the server. The examples use the installed MariaDB client package, version 1:10.11.14-0ubuntu0.24.04.1, whose converter reports program version 1.1.

Allow about fifteen minutes for a small test database, plus the time needed for a backup and a maintenance window if the tables are busy. You need a MariaDB account that can inspect and alter the target tables, the mariadb-convert-table-format command from mariadb-client, and enough free space for the server to rebuild tables. The command changes table storage. Treat production use as a planned database operation, not as a harmless inspection.

Checkpoint: Do not continue until you have named the database, selected the exact tables, confirmed a recovery path, and agreed when a table lock or slower query performance is acceptable.

1. Confirm which command is installed

MariaDB renamed the old mysql_convert_table_format client to mariadb-convert-table-format. The old name remains available here as a symlink. Check both names before putting one into a script:

$ command -v mariadb-convert-table-format
/usr/bin/mariadb-convert-table-format
$ readlink -f /usr/bin/mysql_convert_table_format
/usr/bin/mariadb-convert-table-format
$ dpkg-query -W -f='${Package} ${Version}\n' mariadb-client
mariadb-client 1:10.11.14-0ubuntu0.24.04.1
$ mariadb-convert-table-format --version
/usr/bin/mariadb-convert-table-format  version 1.1

These are read-only checks and do not require elevated privileges. The command is a Perl script, so its help also says that the DBI and MariaDB driver modules are required. If --version or --help fails, fix the client installation and Perl dependencies before attempting a conversion.

2. Read the installed option shape

Run the local help rather than copying an option from a different MariaDB release:

$ mariadb-convert-table-format --help

The installed program accepts a database followed by zero or more table names. If no table names are supplied, it converts every table in that database. It also accepts wildcard table patterns such as my%. The target engine is selected with --engine=ENGINE, and the installed default is MYISAM.

The local manual uses the older synopsis and calls the engine option --type, while the installed program's help exposes --engine and table arguments. Use the syntax printed by the binary you are actually running. This difference is a useful reason to keep the help output with an operational record.

Checkpoint: Write down the exact table list or wildcard. A bare database name is not a shortcut for a harmless dry run; on this installed command it means all tables in that database.

3. Inspect the current engines

Before changing anything, record the current engine for the tables you intend to touch. The following query is read-only; run it with your normal MariaDB client and replace the database name:

$ mariadb --user=DB_USER --database=DB_NAME --execute="SELECT TABLE_NAME, ENGINE FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'DB_NAME' AND TABLE_NAME IN ('orders', 'audit_log');"
+------------+--------+
| TABLE_NAME | ENGINE |
+------------+--------+
| orders     | InnoDB |
| audit_log  | InnoDB |
+------------+--------+

The exact table drawing varies by client settings. Save the names and engines somewhere you can compare after the operation. Also check table size, replication state and application dependencies according to your normal change procedure. The converter is not a migration planner: it will not decide whether MyISAM, InnoDB or another engine is appropriate for your workload.

4. Back up and choose a narrow first conversion

Warning: Conversion rebuilds table storage and can disrupt writes. Make a tested logical or physical backup before changing a production table. Keep the original backup until the converted table has passed application checks. If the conversion fails, restore from that backup using your documented MariaDB recovery process; do not assume --force makes the operation reversible.

For a first test, name one non-critical table explicitly and select the engine with the long option:

$ mariadb-convert-table-format \
    --user=DB_USER \
    --host=DB_HOST \
    --engine=InnoDB \
    DB_NAME orders

Replace every uppercase value, and choose an engine that is supported and suitable on the target server. The command uses localhost by default when no host is given. Use --port=PORT for a TCP port and --socket=/path/to/mariadb.sock for a particular local socket. These connection options do not change the table selection.

Do not put a real password in a shell history, process listing or shared runbook. The program's --password=PASSWORD option requires the value inline, and the manual warns that this is insecure. Prefer the account and option-file arrangement approved for your host. If an automation system supplies credentials, use its protected secret handling and check that command-line arguments are not logged.

5. Verify the converted table

When the command returns, do not treat a quiet terminal as proof of the result. Query the server again:

$ mariadb --user=DB_USER --database=DB_NAME --execute="SELECT TABLE_NAME, ENGINE FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'DB_NAME' AND TABLE_NAME = 'orders';"
+------------+--------+
| TABLE_NAME | ENGINE |
+------------+--------+
| orders     | InnoDB |
+------------+--------+

Run a small application-level read against the table and check the server error log and replication monitoring used by your site. A successful conversion does not validate query plans, foreign-key expectations, locking behaviour or application assumptions. If the engine is unchanged, inspect the command's exit status and diagnostic output, then check the account privileges and server logs before trying again.

For more detail, add --verbose. The installed help describes it as diagnostic output, not a preview mode. It does not turn a write operation into a dry run.

6. Expand the change only after the test

Once the single-table test is accepted, pass several tables explicitly:

$ mariadb-convert-table-format \
    --user=DB_USER \
    --engine=InnoDB \
    DB_NAME orders audit_log session_data

You can use a wildcard supported by the installed command when the naming rule is unambiguous:

$ mariadb-convert-table-format --user=DB_USER --engine=InnoDB DB_NAME 'archive_%'

Quote wildcard patterns so the shell does not expand them against local filenames. Review the matching table names in advance, and repeat the information schema query afterwards. Avoid the bare form mariadb-convert-table-format DB_NAME unless converting every table is explicitly intended and scheduled.

--force continues when errors occur. That can leave a batch partly converted, so use it only when your change plan explains how to identify failures and recover each table. It is not a repair option and it does not roll back earlier successful conversions.

7. Record the result and undo deliberately

Keep the command, package version, target list, before-and-after engine query, exit status and any diagnostics with the change record. If the new engine is unsuitable, convert the affected table back to the recorded original engine in a maintenance window, then run the same verification query. If data integrity or availability is in doubt, stop further conversions and restore from the tested backup instead of repeatedly changing engines.

Done means