MySQL 8.0 Reference Manual Including MySQL NDB Cluster 8.0

2.11.3 What the MySQL Upgrade Process Upgrades

Installing a new version of MySQL may require upgrading these parts of the existing installation:

Two distinct version numbers are associated with parts of the installation that may require upgrading:

In both cases, the actual version applicable to the existing MySQL installation is stored in the data dictionary, and the current expected version is compiled into the new version of MySQL. When an actual version is lower than the current expected version, those parts of the installation associated with that version must be upgraded to the current version. If both versions indicate an upgrade is needed, the data dictionary upgrade must occur first.

As a reflection of the two distinct versions just mentioned, the upgrade occurs in two steps:

The data dictionary upgrade (step 1) is the responsibility of the server, which performs this task as necessary at startup unless invoked with an option that prevents it from doing so. The option is --upgrade=NONE as of MySQL 8.0.16, --no-dd-upgrade prior to MySQL 8.0.16.

If the data dictionary is out of date but the server is prevented from upgrading it, the server will not run and exits with an error. For example:

[ERROR] [MY-013381] [Server] Server shutting down because upgrade is
required, yet prohibited by the command line option '--upgrade=NONE'.
[ERROR] [MY-010334] [Server] Failed to initialize DD Storage Engine
[ERROR] [MY-010020] [Server] Data Dictionary initialization failed.

Some changes to the responsibility for step 2 occurred in MySQL 8.0.16:

Depending on the version of MySQL to which you are upgrading, the instructions in In-Place Upgrade and Logical Upgrade indicate whether the server performs all upgrade tasks or whether you must also invoke mysql_upgrade after server startup.

Note

Because the server performs step 2 as of MySQL 8.0.16, mysql_upgrade is unneeded and is deprecated as of that version, and will be removed in a future MySQL version.

Most aspects of what occurs during step 2 are the same prior to and as of MySQL 8.0.16, although different command options may be needed to achieve a particular effect.

As of MySQL 8.0.16, the --upgrade server option controls whether and how the server performs an automatic upgrade at startup:

FORCE is useful to force step 2 actions to be performed if the server thinks they are not necessary (such as when the mysql_upgrade_info file in the data directory already contains the current server version). One way that FORCE differs from AUTO is that with FORCE, the server re-creates system tables such as help tables or time zone tables if they are missing.

The following list shows upgrade commands prior to MySQL 8.0.16 and the equivalent commands for MySQL 8.0.16 and higher:

Prior to MySQL 8.0.16, certain mysql_upgrade options affect the actions it performs. The following table shows which server --upgrade option values to use as of MySQL 8.0.16 to achieve similar effects. (These are not necessarily exact equivalents because a given --upgrade option value may have additional effects.)

mysql_upgrade Option Server Option
--skip-sys-schema --upgrade=NONE or --upgrade=MINIMAL
--upgrade-system-tables --upgrade=NONE or --upgrade=MINIMAL
--force --upgrade=FORCE

Additional notes about what occurs during upgrade step 2: