You can use the upgrade checker utility to check MySQL 5.7 server instances, and MySQL 8.0 server instances at another GA status release within the MySQL 8.0 release series, for compatibility errors and issues for upgrading. If you invoke checkForServerUpgrade() without specifying a MySQL Server instance, the instance currently connected to the global session is checked. To see the currently connected instance, issue the \status command.

The upgrade checker utility can check the configuration file (my.cnf or my.ini) for the server instance. The utility checks for any system variables that are defined in the configuration file but have been removed in the target MySQL Server release, and also for any system variables that are not defined in the configuration file and will have a different default value in the target MySQL Server release. For these checks, when you invoke checkForServerUpgrade(), you must provide the file path to the configuration file.

The upgrade checker utility can generate its output in text format, which is the default, or in JSON format, which might be simpler to parse and process for use in devops automation.

The upgrade checker utility can operate over either an X Protocol connection or a classic MySQL protocol connection, using either TCP or Unix sockets. You can create the connection beforehand, or specify it as arguments to the function. The utility always creates a new session to connect to the server, so the MySQL Shell global session is not affected.

Up to MySQL Shell 8.0.20, the user account that is used to run the upgrade checker utility must have ALL privileges. From MySQL Shell 8.0.21, the user account requires RELOAD, PROCESS, and SELECT privileges.

The upgrade checker utility has the following signature:

checkForServerUpgrade (ConnectionData connectionData, Dictionary options)

Both arguments are optional. The first provides connection data if the connection does not already exist, and the second is a dictionary that you can use to specify the following options:

For example, the following commands verify then check the MySQL server instance currently connected to the global session, with output in text format:

mysqlsh> \status
MySQL Shell version 8.0.29
...
Server version:               5.7.33-log MySQL Community Server (GPL)
...
mysqlsh> util.checkForServerUpgrade()

The following command checks the MySQL server at URI user@example.com:3306 for upgrade to MySQL Server release 8.0.27. The user password and the configuration file path are supplied as part of the options dictionary, and the output is returned in the default text format:

mysqlsh> util.checkForServerUpgrade('user@example.com:3306', 
           {"password":"password", "targetVersion":"8.0.27", "configPath":"C:/ProgramData/MySQL/MySQL Server 8.0/my.ini"})

The following command checks the same MySQL server for upgrade to the MySQL Server release number that matches the current MySQL Shell release number (the default), and returns JSON output for further processing:

mysqlsh> util.checkForServerUpgrade('user@example.com:3306', 
           {"password":"password", "outputFormat":"JSON", "configPath":"C:/ProgramData/MySQL/MySQL Server 8.0/my.ini"})

You can start the upgrade checker utility from the command line using the mysqlsh command interface. For information on this syntax, see Section 5.8, “API Command Line Integration”. The following example checks a MySQL server for upgrade to release 8.0.27, and returns JSON output:

mysqlsh -- util checkForServerUpgrade user@localhost:3306 
                   --target-version=8.0.27 --output-format=JSON --config-path=/etc/mysql/my.cnf

The connection data can also be specified as named options grouped together by using curly brackets, as in the following example, which also shows that lower case and hyphens can be used for the method name rather than camelCase:

mysqlsh -- util check-for-server-upgrade { --user=user --host=localhost --port=3306 } 
  --target-version=8.0.27 --output-format=JSON --config-path=/etc/mysql/my.cnf

The following example uses a Unix socket connection and shows the older format for invoking the utility from the command line, which is still valid:

./bin/mysqlsh --socket=/tmp/mysql.sock --user=user -e "util.checkForServerUpgrade()"

To get help for the upgrade checker utility, issue:

mysqlsh> util.help("checkForServerUpgrade")

util.checkForServerUpgrade() does not return a value (before MySQL Shell 8.0.13, the value 0, 1, or 2 was returned).

When you invoke the upgrade checker utility, MySQL Shell connects to the server instance and tests the settings described at Preparing Your Installation for Upgrade. For example:

The MySQL server at example.com:3306, version
5.7.33-enterprise-commercial-advanced - MySQL Enterprise Server - Advanced Edition (Commercial),
will now be checked for compatibility issues for upgrade to MySQL 8.0.37...

1) Usage of old temporal type
  No issues found

2) Usage of db objects with names conflicting with new reserved keywords
  Warning: The following objects have names that conflict with new reserved keywords. 
  Ensure queries sent by your applications use `quotes` when referring to them or they will result in errors.
  More information: https://dev.mysql.com/doc/refman/en/keywords.html

  dbtest.System - Table name
  dbtest.System.JSON_TABLE - Column name
  dbtest.System.cube - Column name

3) 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.
  More information: https://docs.oracle.com/cd/E17952_01/mysql-8.0-en/charset-unicode-utf8mb3.html 
 
  dbtest.view1.col1 - column's default character set: utf8 

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

5) Partitioned tables using engines with non native partitioning
  Error: In MySQL 8.0 storage engine is responsible for providing its own
  partitioning handler, and the MySQL server no longer provides generic
  partitioning support. InnoDB and NDB are the only storage engines that
  provide a native partitioning handler that is supported in MySQL 8.0. A
  partitioned table using any other storage engine must be altered—either to
  convert it to InnoDB or NDB, or to remove its partitioning—before upgrading
  the server, else it cannot be used afterwards.
  More information:
    https://docs.oracle.com/cd/E17952_01/mysql-8.0-en/upgrading-from-previous-series.html#upgrade-configuration-changes

  dbtest.part1_hash - MyISAM engine does not support native partitioning

..... 

Errors:   7
Warnings: 36
Notices:  0

7 errors were found. Please correct these issues before upgrading to avoid compatibility issues.
  

When you select JSON output using the outputFormat dictionary option, the JSON object returned by the upgrade checker utility has the following key-value pairs: