MySQL Shell 8.0.4: Introducing “Upgrade checker” utility
Mysql 11-Feb-2019

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:mysqlsh root:@localhost:3306 -e "util.checkForServerUpgrade();"
  • 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:
    mysql-js> util.checkForServerUpgrade("root@localhost:3306");
    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:

mysql-js> util.checkForServerUpgrade("root@localhost:3306")
The MySQL server at localhost:3306 will now be checked for compatibility issues for upgrade to MySQL 8.0...
MySQL version: 5.7.19 - MySQL Community Server (GPL)

1) Usage of db objects with names conflicting with reserved keywords in 8.0
No issues found

2) Usage of utf8mb3 charset
Warning: The following objects use the utf8mb3 character set. It is recommended to convert them to use utf8mb4 instead, for improved Unicode support. - column's default character set: utf8 - column's default character set: utf8

3) Usage of use ZEROFILL/display length type attributes
Notice: The following table columns specify a ZEROFILL/display length attributes. Please be aware that they will be ignored in MySQL 8.0

test.big_table.ORDINAL_POSITION - bigint(21) unsigned

4) Issues reported by 'check table x for upgrade' command
No issues found

5) Table names in the mysql schema conflicting with new tables in 8.0
No issues found

6) Usage of old temporal type
No issues found

7) Foreign key constraint names longer than 64 characters
No issues found

No fatal errors were found that would prevent a MySQL 8 upgrade, but some potential issues were detected. Please ensure that the reported issues are not significant before upgrading.

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!