It has been over a year since we made Upgrade Checker utility available as part of MySQL Shell. While purpose of Upgrade Checker remains the same, to provide ability to check your server before attempting an upgrade, the tool has evolved and this post provides brief overview of the changes.

Multiple version support

Although Upgrade Checker was originally intended to check specifically 5.7 server versions for upgrade to version 8.0, its support has been extended to verify upgrades to any of the 8.0.* versions from any version starting at 5.7. While our intention is to minimize breaking changes between 8.0.* versions, they do happen (e.g. removal of system variables or some parts of syntax), and you can use Upgrade Checker to check if your system is affected.

Remember even if you want to check upgrade to an older version (say. 8.0.14), it is always best to use most up to date MySQL Shell, as you will get all the checks and bug fixes and desired server version can be set using “targetVersion” option.

JSON output

In most scenarios users will prefer standard text output offered by default by Upgrade Checker. However if you would like e.g. to create a bot to test your servers automatically or to process Upgrade Checker output and display it in some other way, now Upgrade Checker also offers nicely formatted, easy to parse JSON output. To get it specify “outputFormat” option with value “JSON” or use “–json” MySQL Shell command line option (that wraps whole Shell output in JSON). Details of JSON output can be found in our documentation.

Even more checks

With almost every new MySQL Shell release new checks are added to the Upgrade Checker. Most of them are fully automatic but we added two types that need more attention.

The first one aims to check for removed system variables. While it is fully automatic when checking 8.0 instances in 5.7 we need to access configuration files. In order to take advantage of these checks you need to specify path to the configuration file to scan using ‘configPath’ option. Path needs to be local so if you are checking remote servers you will need to download the file to the machine you run MySQL Shell on.

The other one are what we call manual checks. In instances where automatic check is not available and yet we think that something should be carefully considered before upgrade we will provide guidelines what to do and where to find more information. So far we only have one – describing new default authentication plugin considerations for 5.7 to 8.0 upgrade.

Interface changes

Upgrade Checker’s interface changed to accommodate new requirements and currently looks like:

void checkForServerUpgrade (ConnectionData connectionData, Dictionary options)

There is no return value. The first parameter is still connection data either in the form of URI (e.g. ‘root@localhost’) or dictionary. The second is an options dictionary where following keys can be defined:

• configPath – local path to MySQL server configuration file,
• outputFormat – value can be either TEXT (default) or JSON.
• targetVersion – version to which upgrade will be checked (default matches current version of MySQL Shell)
• password – password for connection if you prefer to specify it here.

Both parameters are optional. However, as before, if you do not specify connection data you need to have an active Shell global session with a server.

Usage examples

As before Upgrade Checker is available as a function of Util global Shell module in JavaScript and Python modes.

In interactive mode you can call it simply like this:

mysql-js> util.checkForServerUpgrade('user@example.com:3306', {"targetVersion":"8.0.11"});

If you prefer to use Upgrade Checker without entering Shell interactive mode you can use the same syntax with Shell’s -e command line option or more conveniently use the recent “API Command Line integration” like this:

mysqlsh -- util check-for-server-upgrade root@localhost --target-version=8.0.15 --output-format=JSON --config-path=/etc/mysql/my.cn

For detailed instructions on how to use Upgrade Checker please consult our documentation.

Thanks for using MySQL!