您可以使用升级检查器实用程序检查 MySQL 5.7 服务器实例和 MySQL 8.0 版本系列中另一个 GA 状态版本的 MySQL 8.0 服务器实例，以查找兼容性错误和升级问题。如果您在 checkForServerUpgrade()未指定 MySQL 服务器实例的情况下调用，则会检查当前连接到全局会话的实例。要查看当前连接的实例，请发出\status命令。

升级检查器实用程序可以检查服务器实例的配置文件（my.cnf或my.ini）。该实用程序检查配置文件中定义但已在目标 MySQL Server 版本中删除的任何系统变量，以及配置文件中未定义且在目标 MySQL 中具有不同默认值的任何系统变量服务器发布。对于这些检查，当您调用时 checkForServerUpgrade()，您必须提供配置文件的文件路径。

升级检查器实用程序可以生成文本格式的输出，这是默认格式，也可以生成 JSON 格式的输出，后者可能更易于解析和处理以用于 devops 自动化。

升级检查器实用程序可以使用 TCP 或 Unix 套接字在 X 协议连接或经典 MySQL 协议连接上运行。您可以预先创建连接，或将其指定为函数的参数。该实用程序始终创建一个新会话来连接到服务器，因此 MySQL Shell 全局会话不受影响。

在 MySQL Shell 8.0.20 之前，用于运行升级检查器实用程序的用户帐户必须具有ALL 特权。从 MySQL Shell 8.0.21 开始，用户帐户需要 RELOAD、 PROCESS和 SELECT权限。

升级检查器实用程序具有以下签名：

checkForServerUpgrade (ConnectionData connectionData, Dictionary options)

这两个参数都是可选的。如果连接尚不存在，第一个提供连接数据，第二个是可用于指定以下选项的字典：

例如，以下命令验证然后检查当前连接到全局会话的 MySQL 服务器实例，输出为文本格式：

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

以下命令检查位于 URI 的 MySQL 服务器 user@example.com:3306是否升级到 MySQL 服务器版本 8.0.27。用户密码和配置文件路径作为选项字典的一部分提供，输出以默认文本格式返回：

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

以下命令检查同一个 MySQL 服务器是否升级到与当前 MySQL Shell 版本号（默认值）匹配的 MySQL 服务器版本号，并返回 JSON 输出以供进一步处理：

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

您可以使用mysqlsh命令界面 从命令行启动升级检查器实用程序。有关此语法的信息，请参阅 第 5.8 节 “API 命令行集成”。以下示例检查 MySQL 服务器是否升级到 8.0.27 版，并返回 JSON 输出：

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

连接数据也可以指定为使用大括号组合在一起的命名选项，如以下示例所示，这也表明小写和连字符可以用于方法名称而不是驼峰式：

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

以下示例使用 Unix 套接字连接并显示用于从命令行调用该实用程序的旧格式，该格式仍然有效：

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

要获得有关升级检查器实用程序的帮助，请发出：

mysqlsh> util.help("checkForServerUpgrade")

util.checkForServerUpgrade()不返回值（在 MySQL Shell 8.0.13 之前，返回值 0、1 或 2）。

当您调用升级检查器实用程序时，MySQL Shell 连接到服务器实例并测试准备升级安装中描述的设置。例如：

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.29...

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://mysql.net.cn/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://mysql.net.cn/doc/refman/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://mysql.net.cn/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-configuration-changes

  dbtest.part1_hash - MyISAM engine does not support native partitioning

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

7) Usage of obsolete MAXDB sql_mode flag
  No issues found

8) Usage of obsolete sql_mode flags
  No issues found

9) ENUM/SET column definitions containing elements longer than 255 characters 
  No issues found

10) Usage of partitioned tables in shared tablespaces
  Error: The following tables have partitions in shared tablespaces. Before upgrading to 8.0 they need 
  to be moved to file-per-table tablespace. You can do this by running query like 
  'ALTER TABLE table_name REORGANIZE PARTITION X INTO 
    (PARTITION X VALUES LESS THAN (30) TABLESPACE=innodb_file_per_table);'
  More information: https://mysql.net.cn/doc/refman/8.0/en/mysql-nutshell.html#mysql-nutshell-removals

  dbtest.table1 - Partition p0 is in shared tablespace tbsp4
  dbtest.table1 - Partition p1 is in shared tablespace tbsp4 

11) Circular directory references in tablespace data file paths
  No issues found

12) Usage of removed functions
  Error: Following DB objects make use of functions that have been removed in
    version 8.0. Please make sure to update them to use supported alternatives
    before upgrade.
  More information:
    https://mysql.net.cn/doc/refman/8.0/en/mysql-nutshell.html#mysql-nutshell-removals

  dbtest.view1 - VIEW uses removed function PASSWORD

13) Usage of removed GROUP BY ASC/DESC syntax 
  Error: The following DB objects use removed GROUP BY ASC/DESC syntax. They need to be altered so that 
  ASC/DESC keyword is removed from GROUP BY clause and placed in appropriate ORDER BY clause.
  More information: https://mysql.net.cn/doc/relnotes/mysql/8.0/en/news-8-0-13.html#mysqld-8-0-13-sql-syntax 

  dbtest.view1 - VIEW uses removed GROUP BY DESC syntax
  dbtest.func1 - FUNCTION uses removed GROUP BY ASC syntax 

14) Removed system variables for error logging to the system log configuration
  No issues found

15) Removed system variables
  Error: Following system variables that were detected as being used will be
    removed. Please update your system to not rely on them before the upgrade.
  More information: https://mysql.net.cn/doc/refman/8.0/en/added-deprecated-removed.html#optvars-removed

  log_builtin_as_identified_by_password - is set and will be removed
  show_compatibility_56 - is set and will be removed

16) System variables with new default values
  Warning: Following system variables that are not defined in your
    configuration file will have new default values. Please review if you rely on
    their current values and if so define them before performing upgrade.
  More information: https://mysqlserverteam.com/new-defaults-in-mysql-8-0/

  back_log - default value will change
  character_set_server - default value will change from latin1 to utf8mb4
  collation_server - default value will change from latin1_swedish_ci to
    utf8mb4_0900_ai_ci
  event_scheduler - default value will change from OFF to ON
[...]

17) Zero Date, Datetime, and Timestamp values
  Warning: By default zero date/datetime/timestamp values are no longer allowed
    in MySQL, as of 5.7.8 NO_ZERO_IN_DATE and NO_ZERO_DATE are included in
    SQL_MODE by default. These modes should be used with strict mode as they will
    be merged with strict mode in a future release. If you do not include these
    modes in your SQL_MODE setting, you are able to insert
    date/datetime/timestamp values that contain zeros. It is strongly advised to
    replace zero values with valid ones, as they may not work correctly in the
    future.
  More information:
    https://lefred.be/content/mysql-8-0-and-wrong-dates/

  global.sql_mode - does not contain either NO_ZERO_DATE or NO_ZERO_IN_DATE
    which allows insertion of zero dates
  session.sql_mode -  of 2 session(s) does not contain either NO_ZERO_DATE or
    NO_ZERO_IN_DATE which allows insertion of zero dates
  dbtest.date1.d - column has zero default value: 0000-00-00

18) Schema inconsistencies resulting from file removal or corruption
  No issues found

19) Tables recognized by InnoDB that belong to a different engine
  No issues found

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

21) New default authentication plugin considerations
  Warning: The new default authentication plugin 'caching_sha2_password' offers
    more secure password hashing than previously used 'mysql_native_password'
    (and consequent improved client connection authentication). However, it also
    has compatibility implications that may affect existing MySQL installations. 
    If your MySQL installation must serve pre-8.0 clients and you encounter
    compatibility issues after upgrading, the simplest way to address those
    issues is to reconfigure the server to revert to the previous default
    authentication plugin (mysql_native_password). For example, use these lines
    in the server option file:
    
    [mysqld]
    default_authentication_plugin=mysql_native_password
    
    However, the setting should be viewed as temporary, not as a long term or
    permanent solution, because it causes new accounts created with the setting
    in effect to forego the improved authentication security.
    If you are using replication please take time to understand how the
    authentication plugin changes may impact you.
  More information:
    https://mysql.net.cn/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password-compatibility-issues
    https://mysql.net.cn/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password-replication

Errors:   7
Warnings: 36
Notices:  0

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

当您使用 outputFormat字典选项选择 JSON 输出时，升级检查器实用程序返回的 JSON 对象具有以下键值对：