Утилита проверки обновления 12.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 Server, проверяется экземпляр, подключенный в данный момент к глобальной сессии. Чтобы увидеть текущий подключенный экземпляр, выполните команду \status.
Утилита проверки обновления не поддерживает проверку экземпляров MySQL Server, более старых, чем MySQL 5.7.
MySQL Server поддерживает только обновление между выпусками GA начиная с версии 5.7. Обновления с версий, не являющихся GA, не поддерживаются. Более подробную информацию о поддерживаемых путях обновления см. в .
Утилита проверки обновления может проверять файл конфигурации (my.cnf или my.ini) для экземпляра сервера. Утилита проверяет наличие системных переменных, определенных в файле конфигурации, но удаленных в целевой версии MySQL Server, а также системных переменных, которые не определены в файле конфигурации и будут иметь другое значение по умолчанию в целевой версии MySQL Server. Для этих проверок, при вызове checkForServerUpgrade(), необходимо указать путь к файлу конфигурации.
Утилита проверки обновления может генерировать вывод в текстовом формате, который является по умолчанию, или в формате JSON, который может быть проще для парсинга и обработки при использовании в автоматизации DevOps.
Запуск утилиты
Утилита проверки обновления может работать как по протоколу X, так и по классическому протоколу MySQL, используя 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 Server, который вы проверяете, например,C:\ProgramData\MySQL\MySQL Server 8.1\my.ini. Если вы опустите путь к файлу, и утилите проверки обновления потребуется выполнить проверку, требующую файл конфигурации, эта проверка завершится ошибкой с сообщением, информирующим вас о необходимости указать путь к файлу.-
outputFormat Формат, в котором возвращается вывод утилиты проверки обновления. По умолчанию, если вы опустите опцию, используется текстовый формат (
TEXT). Если вы укажетеJSON, вместо этого будет возвращён отформатированный вывод JSON в формате, описанном в JSON Output от утилиты проверки обновления.-
include - …
-
exclude - …
-
list - …
Например, следующие команды проверяют, а затем проверяют экземпляр MySQL Server, подключенный в данный момент к глобальной сессии, с выводом в текстовом формате:
mysqlsh> \status
\status
MySQL Shell version 8.1.0-commercial
...
Server version: 8.1.0-commercial MySQL Enterprise Server - Commercial
...
mysqlsh> util.checkForServerUpgrade()
…
…
mysqlsh> util.checkForServerUpgrade('user@example.com:3306',
{"password":"password", "outputFormat":"JSON",
"configPath":"C:/ProgramData/MySQL/MySQL Server 8.0/my.ini"})
…
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
…
./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:
links...
Errors: 7
Warnings: 36
Notices: 0
7 errors were found. Please correct these issues before upgrading to avoid compatibility issues.
- …
- …
- …
Проверки при обновлении
Проверка обновления выполняет следующие проверки:
oldTemporal: Проверяет использование устаревших временных типов.-
syntax: Проверяет синтаксис процедур, триггеров и событий, используя язык SQL, соответствующий версии целевого сервера.Выполните эту проверку при обновлении:
с LTS-серии до следующей LTS или Innovation-серии. Например, с 8.0 до 8.4.
с Innovation-серии до следующей LTS-серии. Например, с 9.1 до 9.7.
внутри Innovation-серии. Например, с 9.1 до 9.2.
reservedKeywords: Проверяет имена объектов базы данных на наличие конфликтов с зарезервированными ключевыми словами. См. .utf8mb3: Проверяет использование набора символов utf8mb3. Хотя utf8mb3 поддерживается, для улучшенной поддержки Unicode рекомендуется использовать utf8mb4. См. .mysqlSchema: Проверяет имена таблиц в схемеmysqlна наличие конфликтов с таблицами целевой версии.nonNativePartitioning: Проверяет таблицы с разбиением по неродному принципу разбиения.foreignKeyLength: Проверяет имена ограничений внешних ключей, длина которых превышает 64 символа. См. .maxdbSqlModeFlags: Проверяет использование устаревшего флагаMAXDB.obsoleteSqlModeFlags: Проверяет использование устаревших флагов.enumSetElementLength: Проверяет определения столбцовENUM/SET, содержащих элементы длиной более 255 символов.partitionedTablesInSharedTablespaces: Проверяет разбиение таблиц в общих табличных пространствах.circularDirectory: Проверяет наличие циклических ссылок на каталоги в путях данных файлов табличного пространства.removedFunctions: Проверяет функции, удалённые в целевой версии MySQL.groupbyAscSyntax: Проверяет синтаксисGROUP BY ASCилиDESC.removedSysLogVars: Проверяет старые системные переменные, используемые для настройки системного ведения журнала.-
sysvar: Выполняет следующие проверки:Проверяет системные переменные с другими значениями по умолчанию в целевой версии.
Проверяет системные переменные на допустимые значения.
Проверяет системные переменные, используемые в источнике, но устаревшие или удалённые в целевой версии. Это означает, что системные переменные установлены в источнике с нестандартными значениями.
zeroDates: Проверяет нулевые значения дат, datetime и timestamp.schemaInconsistency: Проверяет несоответствия схемы, возникшие из-за удаления или повреждения файлов.ftsInTablename: Проверяет имена таблиц, содержащиеFTS, которое не поддерживается в MySQL 8.0 и выше.engineMixup: Проверяет таблицы InnoDB, распознанные 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: Проверяет ошибки в определениях столбцов.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. Он может быть одним из следующих: Schema, Table, View, Column, Index, ForeignKey, Routine, Event, Trigger, SystemVariable, User, Tablespace или Plugin.
- manualChecks
-
Массив JSON-объектов, по одному на каждую отдельную проблему обновления, которая важна для вашего пути обновления и требует проверки вручную (например, изменение плагина аутентификации по умолчанию в MySQL 8.0). Каждый JSON-объект имеет следующие пары ключ-значение:
- id
Идентификатор ручной проверки, который является уникальной строкой.
- title
Краткое описание ручной проверки.
- description
Подробное описание ручной проверки с информацией и советами.
- documentationLink
Если доступно, ссылка на документацию с дополнительной информацией или советами.
© 2025 Oracle
Licensed under the GPLv2 License.
