11.1 升级检查器实用程序

该util.checkForServerUpgrade()函数是一个升级检查实用程序，可让您验证 MySQL 服务器实例是否已准备好升级。您可以选择计划升级到的目标 MySQL Server 版本，范围从第一个 MySQL Server 8.0 通用 (GA) 版本 (8.0.11) 到与当前 MySQL Shell 版本号匹配的 MySQL Server 版本号。升级检查实用程序执行与指定目标版本相关的自动检查，并建议您应手动进行进一步的相关检查。

关于实用程序

运行实用程序

升级检查器实用程序的 JSON 输出

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

笔记
升级检查实用程序不支持检查 MySQL 5.7 之前版本的 MySQL Server 实例。

MySQL Server 仅支持 GA 版本之间的升级。不支持从 MySQL 5.7 或 8.0 的非 GA 版本升级。有关支持的升级路径的更多信息，请参阅升级路径。

升级检查器实用程序可以检查服务器实例的 配置文件（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)
两个参数都是可选的。第一个提供连接数据（如果连接尚不存在），第二个是可用于指定以下选项的字典：

password
用于运行升级检查程序实用程序的用户帐户的密码。您可以使用此字典选项或作为连接详细信息的一部分提供密码。如果您不提供密码，实用程序会在连接到服务器时提示输入密码。

targetVersion
您计划升级到的目标 MySQL Server 版本。您可以指定从 8.0.11（第一个 MySQL Server 8.0 GA 版本）到与您正在使用的 MySQL Shell 版本具有相同版本号的 MySQL Server 版本的任何版本。如果您指定缩写版本号 8.0，或省略该 targetVersion选项，该实用程序会检查是否升级到与您正在使用的 MySQL Shell 版本的版本号相匹配的 MySQL Server 版本号。

configPath
my.cnf您正在检查的 MySQL 服务器实例的配置文件的本地 路径my.ini，例如 C:\ProgramData\MySQL\MySQL Server 8.0\my.ini.如果省略文件路径，并且升级检查程序实用程序需要运行需要配置文件的检查，则该检查将失败，并显示一条消息，通知您必须指定文件路径。

outputFormat
升级检查器实用程序返回的输出的格式。如果省略该选项，则默认为文本格式 ( TEXT)。如果您指定 JSON，则返回格式良好的 JSON 输出，格式 为升级检查器实用程序的 JSON 输出中列出的格式。

例如，以下命令验证并检查当前连接到全局会话的 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://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://dev.mysql.com/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://dev.mysql.com/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://dev.mysql.com/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://dev.mysql.com/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://dev.mysql.com/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://dev.mysql.com/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://dev.mysql.com/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password-compatibility-issues
    https://dev.mysql.com/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.
在此示例中，对服务器实例执行的检查返回了在检查的服务器上发现的升级方案的一些错误，因此需要进行更改才能将服务器实例升级到目标 MySQL 8.0 版本。

当您进行了所需的更改以清除报告的错误计数时，您还应该考虑进行进一步的更改以删除警告。这些配置改进将使服务器实例与目标版本更加兼容。但是，服务器实例可以成功升级，而无需删除警告。

如本示例所示，升级检查程序实用程序还可能为无法自动化且应手动进行的进一步相关检查提供建议和说明，这些检查被评为警告或通知（信息）级别。

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

服务器地址
MySQL Shell 与所检查的 MySQL 服务器实例的连接的主机名和端口号。

服务器版本
检测到所检查的服务器实例的 MySQL 版本。

目标版本
用于升级检查的目标 MySQL 版本。

错误计数
实用程序发现的错误数。

警告计数
实用程序发现的警告数量。

通知计数
实用程序找到的通知数量。

概括
将在文本输出末尾提供的摘要声明的文本（例如，“未发现已知的兼容性错误或问题。”）。

检查已执行
一组 JSON 对象，一个用于自动检查的每个单独升级问题（例如，已删除函数的使用）。每个 JSON 对象都有以下键值对：

ID
支票的ID，是一个唯一的字符串。

标题
支票的简短描述。

地位
如果检查成功运行，则显示“OK”，否则显示“ERROR”。

描述
检查的详细描述（如果有）包含建议，或者检查运行失败时的错误消息。

文档链接
如果有的话，提供包含更多信息或建议的文档链接。

检测到的问题
JSON 对象的数组（可能为空），表示检查结果中发现的错误、警告或通知。每个 JSON 对象都有以下键值对：

等级
消息级别，错误、警告或通知之一。

数据库对象
标识与消息相关的数据库对象的字符串。

描述
如果可用，包含数据库对象问题的具体描述的字符串。

手动检查
一组 JSON 对象，每个对象对应与您的升级路径相关且需要手动检查的每个单独升级问题（例如，MySQL 8.0 中默认身份验证插件的更改）。每个 JSON 对象都有以下键值对：

ID
手工检查的ID，是唯一的字符串。

标题
手动检查的简短描述。

描述
手动检查的详细说明，包含信息和建议。

文档链接
如果有的话，提供包含更多信息或建议的文档链接。