MySQL Shell 8.0.4: Introducing “Upgrade checker” utility

MySQL 8.0 brings a lot of exciting new features and improvements. To make sure that your 5.7 system is ready for an upgrade there are certain steps you should take, described in our documentation: upgrade prerequisites. To make this process as quick and easy as possible we are introducing in MySQL Shell version 8.0.4 new utility called “Upgrade checker” (UC).

UC is available as a function in Shell’s scripting modes: “util.checkForServerUpgrade” in JavaScript and “util.check_for_server_upgrade” in Python, respectively. Its usage is straightforward, the only thing you need to do is to point the function to the server you want to check. There are a couple ways to do this (all the following examples assume that you are running Shell in JS mode):

  • connect your MySQL Shell session to the desired server, either by command line arguments or the \connect command and then you can call the function without any parameters:
  • or you can specify connection options directly as function arguments – as with many others Shell’s functions,  the simplest form of which is an URI:

    To get a detailed description of connection options, refer to the function help:

Please note that in any case UC creates a new MySQL session to the server so your Shell’s global session remains unaffected.

What UC does is connect to specified server and, if the server version is supported (at the moment only 5.7) and user has enough privileges (ALL privileges with GRANT option), runs a series of checks. If any issues are discovered, it displays them along with any advice targeted at resolving those issues. Not all the issues discovered have the same gravity (they are all tagged either “notice”, “warning”, or “error”) and results in failed upgrade process, but you should consider them all to be able to take full advantage of MySQL 8.0. At the end, UC prints a summary and returns an integer value describing he severity of the issues found:

  • 0 – no issues or only ones categorized as notice,
  • 1 – No fatal errors were found, but some potential issues were detected,
  • 2 – UC found errors that must be fixed before upgrading to 8.0.

Typical UC run will look similar to this:

In this sample run you can see all the checks that UC performs at the moment. There can be different types of incompatibilities between versions. Currently UC is limited mostly to ones related to schema and data stored in the server. But there are also those affecting server execution and configuration e.g. arguments used to start the server. So while we hope that UC makes verifying things more convenient, be sure to familiarize yourself with and consider all the changes that can affect the upgrade process.

This is the first version of the “Upgrade checker” utility. We plan to extend and improve  it in upcoming 8.0 mysqlsh releases. Please provide your feedback and ideas!

Thanks for using MySQL!

11 thoughts on “MySQL Shell 8.0.4: Introducing “Upgrade checker” utility

  1. I’m getting the following error on my test box when I try to run it:

    Util.checkForServerUpgrade: Invalid syntax in account name ‘root@%’ (RuntimeError)

    This happens using the different ways as described above. Any ideas?

    1. Unfortunately there is a bug in Shell 8.0.4 which makes it impossible to run UC with users created in MySQL server like user@’%’ or user@’IP address’. It will be fixed in 8.0.5. The only workaround for now is to use user created like user@’hostname’ to run the tool. Sorry for that.

  2. Great to see this. Would it make sense to have this as part of mysql_upgrade where the process will ask if you want to continue if any shortcomings are found?

    1. Thanks Roel! It makes sense to look for opportunities for further automation and helping users in the upgrade process. But please note the following: When you are upgrading from source to target version (e.g. from 5.7.23 to 8.0.6) the Upgrade Checker is to be run on the source 5.7.23 (pre-check) while mysql_upgrade is run on 8.0.6. At the point in time when you run mysql_upgrade the 8.0.6 is already up and running and there is no way back to 5.7.23 other than restoring a backup or a dump etc.

Leave a Reply

Your email address will not be published. Required fields are marked *