Run mysql_upgrade Safely After a MariaDB Upgrade

After this guide, your running MariaDB instance will have had its system tables updated and its databases checked for compatibility with the installed server version. The command can repair tables it identifies as needing attention, so treat it as a maintenance operation rather than a harmless status check.

Allow a few seconds on a small installation, but much longer for large tables or a busy server. Every checked table is locked while it is processed. You need a recent, restorable backup, a running MariaDB server, the client utilities installed, and an account that can write mysql_upgrade_info in the data directory. The examples use the installed Ubuntu package mariadb-server-core 1:10.11.14-0ubuntu0.24.04.1, whose program reports MariaDB 10.11.14.

1. Confirm the program and the server version

mysql_upgrade is the compatibility name for mariadb-upgrade on this Linux installation. Check both the resolved path and the binary version before using it:

$ command -v mysql_upgrade
/usr/bin/mysql_upgrade
$ readlink -f /usr/bin/mysql_upgrade
/usr/bin/mariadb-upgrade
$ mysql_upgrade --version
mysql_upgrade  Ver 2.1 Distrib 10.11.14-MariaDB, for debian-linux-gnu (x86_64)

The version check matters because the utility is distributed with a MariaDB server version. Its default version check prevents it running when that build does not match the server it connects to. Use --skip-version-check only when you have deliberately verified the combination and understand why it differs.

2. Take and test a backup before changing anything

Make a backup that you can restore, and check that it contains the data and system information your recovery plan requires. The upgrade utility may repair tables and changes to system tables can affect authentication and privileges. Do not start it against the only copy of an important database.

Do not copy a live data directory while MariaDB is writing to it and assume that is a consistent backup. Use your established MariaDB backup procedure, such as a tested dump or a filesystem-consistent backup made with the server stopped. The exact backup command depends on your storage and recovery requirements, so this guide does not invent one.

3. Check whether this run is needed

On MariaDB 10.11, the utility records the server version in mysql_upgrade_info under the data directory. A later invocation can skip the table check when that version has already been processed. Ask the installed program for its decision and preserve the exit status immediately:

$ mysql_upgrade --check-if-upgrade-is-needed
$ status=$?
$ printf 'mysql_upgrade decision status: %s\n' "$status"
mysql_upgrade decision status: 1

Status 1 means no action is required. Status 0 means an upgrade is needed, or that the current version could not be determined. The command may need database connection options from your option files or an explicit user, host, socket and port.

Do not confuse this decision with a successful full check. It only tells you whether the recorded version allows the normal work to be skipped.

4. Run the full upgrade check during a maintenance window

Start the server first, then run the utility with credentials supplied interactively. The password must not be placed in the command line, where it can leak through shell history or process inspection:

$ sudo mysql_upgrade --user=DB_ADMIN --password
Enter password:

Replace DB_ADMIN with an account authorised for the upgrade. sudo is needed only when the account you use does not have the required data-directory access; it does not replace MariaDB authentication. If your installation uses a socket or a remote server, add only the connection options you have verified:

$ sudo mysql_upgrade --user=DB_ADMIN --password \
    --host=DB_HOST --port=3306

The command checks all databases, upgrades the mysql system tables, and attempts repairs for detected table problems. It can also adjust database and table names where the upgrade check requires it. Because tables are locked during processing, applications may block or fail while their tables are being checked. Watch the output and your normal MariaDB logs. Do not interrupt the process merely because a large table is quiet for a while.

For a deliberately repeated check, add --force. This ignores the recorded mysql_upgrade_info version and runs the checks again. Use it when you have a specific reason, such as validating a new installation or investigating an incomplete earlier run, not as a routine extra step.

5. Handle minor releases and partial upgrades

Current MariaDB upgrade tooling can skip a normal minor-version run when its recorded version shows that no check is needed. If you move between major releases, migrate from MySQL, or have changed distribution or server builds, run the full command rather than relying on a skipped check. When a minor upgrade genuinely needs checking, use --force after confirming the backup and maintenance window.

If the run stops because of permissions, fix the ownership or access policy for the MariaDB data directory and mysql_upgrade_info through your normal administration process. Do not make the data directory world-writable. If authentication fails, test the same account with a normal client connection and verify the socket, host, port and option-file groups before repeating the upgrade.

The option --upgrade-system-tables limits the operation to system tables in the mysql database. It does not check or touch tables in other databases, so it is appropriate only when you have separately established that application tables do not need checking.

6. Restart and verify the result

The installed manpage instructs you to stop and restart MariaDB after the utility finishes so changes to system tables take effect. Use your service manager and your normal change procedure:

$ sudo systemctl restart mariadb
$ systemctl is-active mariadb
active
$ mysql_upgrade --version
mysql_upgrade  Ver 2.1 Distrib 10.11.14-MariaDB, for debian-linux-gnu (x86_64)

Then connect with the account your applications use, check that expected databases are present, and run a small application health check. If the service does not return to active, stop there: inspect journalctl -u mariadb and the MariaDB error log, and restore the service using your normal rollback plan. Do not delete database files or downgrade packages as an improvised fix.