mysql_upgrade: Usage, Options & Common CI Errors
mysql_upgrade reconciles system tables with a newer server version.
mysql_upgrade is run after pointing a newer server at an older data directory. The big change to know: MySQL 8.0.16+ does this automatically at startup and removed the standalone tool.
What it does
mysql_upgrade checks and updates the system tables and other metadata to be compatible with the current server version after an in-place upgrade. It fixes incompatibilities introduced between major versions.
Common usage
mysql_upgrade -h 127.0.0.1 -u root -psecret
mysql_upgrade -h 127.0.0.1 -u root -psecret --force
mysql_upgrade -h db -u root -psecret --upgrade-system-tables
# MySQL 8.0.16+: upgrade runs automatically at server startOptions
| Flag | What it does |
|---|---|
| --force | Run even if the server thinks it is up to date |
| --upgrade-system-tables | Only upgrade system tables |
| -u <user> / -p[pass] | Credentials (must be privileged) |
| --skip-sys-schema | Do not install/upgrade the sys schema |
Common errors in CI
-bash: mysql_upgrade: command not found on a MySQL 8.0.16+ image is expected - the tool was removed and the server upgrades data automatically on first start; drop the step. On MySQL 5.7 / MariaDB it is still required, and "Access denied" is the usual privileged-credential issue. Running it against a server still mid-startup fails to connect; gate it behind mysqladmin ping.