Утилита проверки обновления 11.1
Функция util.checkForServerUpgrade() — это утилита проверки обновления, которая позволяет проверить, готовы ли экземпляры сервера MySQL к обновлению. Вы можете выбрать целевую версию MySQL Server, до которой планируется обновление, от первой версии MySQL Server 8.0 General Availability (GA) (8.0.11) до версии MySQL Server, соответствующей текущей версии MySQL Shell. Утилита проверки обновления выполняет автоматические проверки, релевантные указанной целевой версии, и сообщает о дополнительных проверках, которые необходимо выполнить вручную.
О утилите
Вы можете использовать утилиту проверки обновления для проверки экземпляров сервера MySQL 5.7 и экземпляров сервера MySQL 8.x на другой версии GA в серии выпусков MySQL 8.x на предмет ошибок совместимости и проблем с обновлением. Если вы вызываете checkForServerUpgrade() без указания экземпляра сервера MySQL, проверяется экземпляр, подключённый к глобальной сессии. Чтобы увидеть текущий подключённый экземпляр, выполните команду \status.
Утилита проверки обновления не поддерживает проверку экземпляров сервера MySQL, более старых, чем MySQL 5.7.
Сервер MySQL поддерживает только обновление между версиями GA начиная с 5.7. Обновления из версий, не являющихся GA, не поддерживаются. Дополнительную информацию о поддерживаемых путях обновления см. в ...
Утилита проверки обновления может проверять файл конфигурации (my.cnf или my.ini) для экземпляра сервера. Утилита проверяет наличие системных переменных, определённых в файле конфигурации, но удалённых в целевой версии MySQL Server, а также наличие системных переменных, которые не определены в файле конфигурации и будут иметь другое значение по умолчанию в целевой версии MySQL Server. Для этих проверок, когда вы вызываете checkForServerUpgrade(), вы должны предоставить путь к файлу конфигурации.
Утилита проверки обновления может генерировать вывод в текстовом формате, который является по умолчанию, или в формате JSON, который может быть проще для парсинга и обработки при использовании в автоматизации DevOps.
Запуск утилиты
Утилита проверки обновления может работать через соединение X Protocol или классическое соединение MySQL Protocol, используя TCP или сокеты Unix. Вы можете создать соединение предварительно или указать его как аргументы функции. Утилита всегда создаёт новую сессию для подключения к серверу, поэтому глобальная сессия MySQL Shell не затрагивается.
Пользовательский аккаунт, используемый для запуска утилиты проверки обновления, требует прав , , и .
Утилита проверки обновления имеет следующий синтаксис:
checkForServerUpgrade (ConnectionData connectionData, Dictionary options)Оба аргумента являются необязательными. Первый предоставляет данные соединения, если соединение ещё не существует, а второй — словарь, который вы можете использовать для указания следующих параметров:
-
password Пароль для учётной записи пользователя, используемой для запуска утилиты проверки обновления. Вы можете указать пароль с помощью этого параметра словаря или в качестве части данных соединения. Если вы не предоставите пароль, утилита запросит его при подключении к серверу.
-
targetVersion Целевая версия MySQL Server, до которой планируется обновление. Вы можете указать любую версию от 8.0.11 (первая версия MySQL Server 8.0 GA) до версии MySQL Server с тем же номером версии, что и версия MySQL Shell, которую вы используете. Если вы укажете короткую версию, например 8.0, или опустите параметр
targetVersion, утилита проверит обновление до версии MySQL Server, соответствующей версии MySQL Shell, которую вы используете.-
configPath Локальный путь к файлу конфигурации
my.cnfилиmy.iniдля экземпляра MySQL сервера, который вы проверяете, например,C:\ProgramData\MySQL\MySQL Server 8.1\my.ini. Если вы опустите путь к файлу, и утилите проверки обновления потребуется выполнить проверку, требующую файл конфигурации, эта проверка завершится ошибкой с сообщением, информирующим вас о необходимости указать путь к файлу.-
outputFormat Формат, в котором возвращается вывод утилиты проверки обновления. По умолчанию, если вы опустите этот параметр, используется текстовый формат (
TEXT). Если вы укажетеJSON, будет возвращён отформатированный вывод JSON в формате, указанном в Выход JSON из утилиты проверки обновления.-
include - ...
-
exclude - ...
-
list - ...
Например, следующие команды проверяют, а затем проверяют экземпляр сервера MySQL, подключённый к глобальной сессии, с выводом в текстовом формате:
mysqlsh> \status
\status
MySQL Shell version 8.1.0-commercial
...
Server version: 8.1.0-commercial MySQL Enterprise Server - Commercial
...
mysqlsh> util.checkForServerUpgrade()
Следующая команда проверяет сервер MySQL по адресу URI user@example.com:3306 на обновление до версии MySQL Server 8.1.0. Пароль пользователя и путь к файлу конфигурации предоставляются в словаре параметров, а вывод возвращается в стандартном текстовом формате:
mysqlsh> util.checkForServerUpgrade('user@example.com:3306',
{"password":"password", "targetVersion":"8.1.0", "configPath":"C:/ProgramData/MySQL/MySQL Server 8.0/my.ini"})
Следующая команда проверяет тот же сервер MySQL на обновление до версии MySQL Server, соответствующей текущей версии MySQL Shell (по умолчанию), и возвращает вывод 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
Данные соединения также можно указать как именованные параметры, сгруппированные вместе с помощью фигурных скобок, как в следующем примере, который также показывает, что можно использовать строчные буквы и дефисы для имени метода вместо 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
Следующий пример использует сокет Unix и демонстрирует более старый формат вызова утилиты из командной строки, который по-прежнему действителен:
./bin/mysqlsh --socket=/tmp/mysql.sock --user=user -e "util.checkForServerUpgrade()" --js
Режим языка по умолчанию в MySQL Shell — SQL. Чтобы запустить операцию JavaScript из командной строки, необходимо добавить --js к команде. Для использования Python-версии операции, например util.check_for_server_upgrade(), необходимо добавить --py.
Чтобы получить справку по утилите проверки обновления, введите:
mysqlsh> util.help("checkForServerUpgrade")
util.checkForServerUpgrade() не возвращает значения.
При вызове утилиты проверки обновления 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://docs.oracle.com/cd/E17952_01/mysql-8.0-en/charset-unicode-utf8mb3.html
dbtest.view1.col1 - column's default character set: utf8
............................
............................
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://docs.oracle.com/cd/E17952_01/mysql-8.0-en/upgrading-from-previous-series.html#upgrade-caching-sha2-password-compatibility-issues
https://docs.oracle.com/cd/E17952_01/mysql-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.
После внесения необходимых изменений для устранения количества ошибок в отчёте, следует также рассмотреть возможность внесения дополнительных изменений для устранения предупреждений. Эти улучшения конфигурации сделают экземпляр сервера более совместимым с целевой версией. Однако экземпляр сервера может быть успешно обновлён без удаления предупреждений.
Как показано в этом примере, утилита проверки обновления также может предоставить советы и инструкции для дополнительных релевантных проверок, которые нельзя автоматизировать, и которые вы должны выполнить вручную, которые имеют уровень либо предупреждения, либо уведомления (информационные).
Проверки при обновлении
Проверка обновления выполняет следующие проверки:
oldTemporal: Проверка использования устаревших типов временных значений.routineSyntax: Проверка синтаксиса процедур на наличие конфликтов с зарезервированными ключевыми словами. См. .reservedKeywords: Проверка имён объектов базы данных на наличие конфликтов с зарезервированными ключевыми словами. См. .utf8mb3: Проверка использования набора символов utf8mb3. Хотя utf8mb3 поддерживается, рекомендуется использовать utf8mb4 для улучшенной поддержки Unicode. См. .mysqlSchema: Проверка имён таблиц в схемеmysqlна наличие конфликтов с таблицами в целевой версии.nonNativePartitioning: Проверка таблиц с разбиением, использующих неродное разбиение.foreignKeyLength: Проверка имён ограничений внешних ключей, длина которых превышает 64 символа. См. .maxdbSqlModeFlags: Проверка использования устаревшего флага,MAXDB.obsoleteSqlModeFlags: Проверка использования устаревших флагов.enumSetElementLength: Проверка определений столбцовENUM/SET, содержащих элементы длиннее 255 символов.partitionedTablesInSharedTablespaces: Проверка таблиц с разбиением в общих табличных пространствах.circularDirectory: Проверка циклических ссылок на каталоги в путях к файлам данных табличного пространства.removedFunctions: Проверка функций, удалённых в целевой версии MySQL.groupbyAscSyntax: Проверка синтаксисаGROUP BY ASCилиDESC.removedSysLogVars: Проверка использования старых системных переменных для настройки системного протоколирования.removedSysVars: Проверка использования системных переменных, используемых в исходной версии, но удалённых в целевой. Это означает, что системные переменные установлены в исходной версии с нестандартными значениями.-
sysVarsNewDefaults: Проверка системных переменных с другими значениями по умолчанию в целевой версии.ПримечаниеПри использовании утилиты проверки обновления для MySQL 5.7.x вам необходимо определить
--configPath. zeroDates: Проверка нулевых значений дат, datetime и timestamp.schemaInconsistency: Проверка несоответствий в схеме, возникших из-за удаления или повреждения файлов.ftsInTablename: Проверка имён таблиц, содержащихFTS, которые не поддерживаются в MySQL 8.0 или выше.engineMixup: Проверка таблиц, распознаваемых InnoDB, но относящихся к другому движку.oldGeometryTypes: Проверка столбцов пространственных данных, созданных в MySQL 5.6.checkTableCommand: Проверка проблем, обнаруженных командой .defaultAuthenticationPlugin: Проверка устаревших подключаемых модулей аутентификации, таких какmysql_native_password.defaultAuthenticationPluginMds: Проверка устаревших подключаемых модулей аутентификации, таких какmysql_native_password.changedFunctionsInGeneratedColumns: Проверка индексов по функциям, семантика которых изменилась в целевой версии.columnsWhichCannotHaveDefaults: Проверка столбцов, которые не могут иметь значений по умолчанию (BLOB, TEXT, GEOMETRY и JSON).invalid57Names: Проверка некорректных имён таблиц и схем, используемых в MySQL 5.7.orphanedObjects: Проверка отсутствующих процедур и событий в MySQL 5.7.dollarSignName: Проверка устаревшего использования одиночных знаков доллара ($) в именах объектов.indexTooLarge: Проверка больших индексов, которые не поддерживаются MySQL 8.0 и выше.emptyDotTableSyntax: Проверка устаревшего синтаксиса., используемого в процедурах.tableNameinvalidEngineForeignKey: Проверка столбцов с внешними ключами, указывающими на таблицы из другого движка базы данных.deprecatedDefaultAuth: Проверка устаревших или некорректных методов аутентификации по умолчанию в системных переменных.deprecatedRouterAuthMethod: Проверка устаревших или некорректных методов аутентификации, используемых внутренними учётными записями MySQL Router.deprecatedTemporalDelimiter: Проверка устаревших временных разделителей в разбиениях таблиц.innodbRowFormat: Проверка таблиц InnoDB с нестандартным форматом строк.authMethodUsage: Проверка устаревших или некорректных методов аутентификации пользователей.pluginUsage: Проверка устаревших или удалённых подключаемых модулей.columnDefinition: Проверка ошибок в определениях столбцов.sysvarAllowedValues: Проверка системных переменных на корректность.invalidPrivileges: Проверка прав доступа пользователей, которые будут удалены.partitionsWithPrefixKeys: Проверка разбиений по ключу, использующих столбцы с индексами префиксных ключей. См. .foreignKeyReferences: Проверка внешних ключей, ссылающихся на неуникальные и частичные индексы.
Вывод в формате JSON из утилиты проверки обновления
При выборе вывода в формате JSON с помощью опции словаря outputFormat, объект JSON, возвращаемый утилитой проверки обновления, содержит следующие пары ключ-значение:
- serverAddress
Имя хоста и номер порта для подключения MySQL Shell к экземпляру сервера MySQL, который проверялся.
- serverVersion
Обнаруженная версия MySQL экземпляра сервера, который проверялся.
- targetVersion
Целевая версия MySQL для проверок обновления.
- errorCount
Количество ошибок, обнаруженных утилитой.
- warningCount
Количество предупреждений, обнаруженных утилитой.
- noticeCount
Количество сообщений, обнаруженных утилитой.
- summary
Текст сводного сообщения, которое будет предоставлено в конце текстового вывода (например, «Известные проблемы совместимости или ошибки не обнаружены»).
- checksPerformed
-
Массив объектов JSON, по одному для каждой отдельной проблемы обновления, которая автоматически проверялась (например, использование удалённых функций). Каждый объект JSON имеет следующие пары ключ-значение:
- id
Идентификатор проверки, уникальная строка.
- title
Краткое описание проверки.
- status
«OK», если проверка выполнена успешно, «ERROR» в противном случае.
- description
Подробное описание проверки (если доступно), включающее рекомендации или сообщение об ошибке, если проверка не выполнена.
- documentationLink
Если доступно, ссылка на документацию с дополнительной информацией или рекомендациями.
- detectedProblems
-
Массив (который может быть пустым) объектов JSON, представляющих ошибки, предупреждения или сообщения, которые были обнаружены в результате проверки. Каждый объект JSON имеет следующие пары ключ-значение:
- level
Уровень сообщения: Error, Warning или Notice.
- dbObject
Строка, идентифицирующая объект базы данных, к которому относится сообщение.
- description
Если доступно, строка с конкретным описанием проблемы с объектом базы данных.
- dbObjectType
Тип
dbObject. Может быть одним из следующих: Схема, Таблица, Вид, Столбец, Индекс, Внешний ключ, Процедура, Событие, Триггер, Системная переменная, Пользователь, Табличное пространство или Подключаемый модуль.
- manualChecks
-
Массив объектов JSON, по одному для каждой отдельной проблемы обновления, которая актуальна для вашего пути обновления и требует проверки вручную (например, изменения подключаемого модуля аутентификации по умолчанию в MySQL 8.0). Каждый объект JSON имеет следующие пары ключ-значение:
- id
Идентификатор проверки вручную, уникальная строка.
- title
Краткое описание проверки вручную.
- description
Подробное описание проверки вручную с информацией и рекомендациями.
- documentationLink
Если доступно, ссылка на документацию с дополнительной информацией или рекомендациями.
© 2025 Oracle
Licensed under the GPLv2 License.
