MySQL :: MySQL Shell 8.0 :: 8.1 アップグレードチェッカユーティリティ

MySQL Shell 8.0 / MySQL Shell ユーティリティ / アップグレードチェッカユーティリティ

このページは機械翻訳したものです。

8.1 アップグレードチェッカユーティリティ

util.checkForServerUpgrade() 関数は、MySQL サーバーインスタンスのアップグレード準備ができているかどうかを確認できるアップグレードチェッカユーティリティです。 MySQL Shell 8.0.13 から、最初の MySQL Server 8.0 General Availability (GA) リリース (8.0.11) から現在の MySQL Shell リリース番号と一致する MySQL Server リリース番号まで、アップグレード先のターゲット MySQL Server リリースを選択できます。アップグレードチェッカユーティリティは、指定されたターゲットリリースに関連する自動チェックを実行し、手動で行う必要がある関連チェックをさらにアドバイスします。

アップグレードチェッカユーティリティを使用して、MySQL 5.7 サーバーインスタンスの互換性エラーおよびアップグレードの問題を確認できます。 MySQL Shell 8.0.13 から、これを使用して、MySQL 8.0 リリースシリーズ内の別の GA ステータスリリースで MySQL 8.0 サーバーインスタンスをチェックすることもできます。 MySQL Server インスタンスを指定せずに checkForServerUpgrade() を起動すると、グローバルセッションに現在接続されているインスタンスがチェックされます。現在接続されているインスタンスを表示するには、\status コマンドを発行します。

注記

アップグレードチェッカユーティリティでは、MySQL 5.7 より前のバージョンの MySQL Server インスタンスのチェックはサポートされていません。
MySQL Server は GA リリース間のアップグレードのみをサポートしています。 MySQL 5.7 または 8.0 の GA 以外のリリースからのアップグレードはサポートされません。サポートされているアップグレードパスの詳細は、アップグレードパスを参照してください。

MySQL Shell 8.0.16 から、アップグレードチェッカユーティリティはサーバーインスタンスの構成ファイル (my.cnf または my.ini) を確認できます。このユーティリティは、構成ファイルで定義されているが、ターゲットの MySQL Server リリースで削除されているシステム変数をチェックします。また、構成ファイルで定義されておらず、ターゲットの MySQL Server リリースでデフォルト値が異なるシステム変数もチェックします。これらのチェックでは、checkForServerUpgrade() を起動するときに、構成ファイルへのファイルパスを指定する必要があります。

アップグレードチェッカユーティリティは、TCP ソケットまたは Unix ソケットを使用して、X プロトコル接続またはクラシック MySQL プロトコル接続を介して動作できます。事前に接続を作成することも、関数の引数として指定することもできます。ユーティリティは常に新しいセッションを作成してサーバーに接続するため、MySQL Shell グローバルセッションは影響を受けません。

MySQL Shell 8.0.20 までは、アップグレードチェッカユーティリティの実行に使用されるユーザーアカウントに ALL 権限が必要です。 MySQL Shell 8.0.21 からは、ユーザーアカウントに RELOAD、PROCESS および SELECT 権限が必要です。

アップグレードチェッカユーティリティでは、テキスト形式 (デフォルト) または JSON 形式 (devops 自動化で使用するための解析および処理が簡単な場合があります) で出力を生成できます。

アップグレードチェッカユーティリティには、次のシグネチャがあります:

checkForServerUpgrade (ConnectionData connectionData, Dictionary options)

どちらの引数もオプションです。接続がまだ存在しない場合、最初の接続データが提供されます。2 番目の接続データは、次のオプションを指定するために使用できるディクショナリです:

password: アップグレードチェッカユーティリティの実行に使用されるユーザーアカウントのパスワード。このディクショナリオプションを使用するか、接続詳細の一部としてパスワードを指定できます。パスワードを指定しない場合、ユーティリティはサーバーへの接続時にパスワードの入力を求めます。
targetVersion: アップグレード先のターゲット MySQL Server バージョン。 MySQL Shell 8.0.22 では、リリース 8.0.11 (最初の MySQL Server 8.0 GA リリース)、8.0.12, 8.0.13, 8.0.14, 8.0.15, 8.0.16, 8.0.17, 8.0.18, 8.0.19, 8.0.20, 8.0.21 または 8.0.22 を指定できます。短い形式のバージョン番号 8.0 を指定するか、targetVersion オプションを省略すると、ユーティリティは現在の MySQL Shell リリース番号と一致する MySQL Server リリース番号へのアップグレードをチェックします。
configPath: 確認する MySQL サーバーインスタンスの my.cnf または my.ini 構成ファイルへのローカルパス (C:\ProgramData\MySQL\MySQL Server 8.0\my.ini など)。ファイルパスを省略し、アップグレードチェッカユーティリティで構成ファイルを必要とするチェックを実行する必要がある場合、そのチェックは失敗し、ファイルパスを指定する必要があることを知らせるメッセージが表示されます。
outputFormat: アップグレードチェッカユーティリティからの出力が返される形式。このオプションを省略した場合のデフォルトはテキスト形式 (TEXT) です。 JSON を指定すると、かわりに、アップグレードチェッカユーティリティの JSON 出力にリストされている形式で整形式の JSON 出力が返されます。

たとえば、次のコマンドは、グローバルセッションに現在接続されている MySQL サーバーインスタンスを確認し、テキスト形式で出力します:

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

次のコマンドは、URI user@example.com:3306 の MySQL サーバーをチェックして、最初の MySQL Server 8.0 GA ステータスリリース (8.0.11) にアップグレードします。ユーザーパスワードと構成ファイルパスは、オプションディクショナリの一部として提供され、出力はデフォルトのテキスト形式で返されます:

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

次のコマンドは、現在の MySQL Shell リリース番号 (デフォルト) と一致する MySQL Server リリース番号にアップグレードするために同じ MySQL サーバーをチェックし、その後の処理のために JSON 出力を返します:

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

MySQL 8.0.13 から、mysqlsh コマンドインタフェースを使用して、コマンドラインからアップグレードチェッカユーティリティを起動できます。この構文の詳細は、セクション5.8「API コマンドラインインタフェース」を参照してください。次の例では、MySQL サーバーのリリース 8.0.21 へのアップグレードをチェックし、JSON 出力を返します:

mysqlsh -- util checkForServerUpgrade user@localhost:3306 --target-version=8.0.21 --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.21 --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.25-enterprise-commercial-advanced - MySQL Enterprise Server - Advanced Edition (Commercial),
will now be checked for compatibility issues for upgrade to MySQL 8.0.22...

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 出力

outputFormat ディクショナリオプションを使用して JSON 出力を選択した場合、アップグレードチェッカユーティリティによって返される JSON オブジェクトには、次のキーと値のペアがあります:

serverAddress

チェックされた MySQL サーバーインスタンスへの MySQL Shell 接続のホスト名およびポート番号。

serverVersion

チェックされたサーバーインスタンスの MySQL バージョンが検出されました。

targetVersion

アップグレードチェックのターゲット MySQL バージョン。

errorCount

ユーティリティで検出されたエラーの数。

warningCount

ユーティリティで検出された警告の数。

noticeCount

ユーティリティによって検出された通知の数。

summary

テキスト出力の最後に提供されるサマリーステートメントのテキスト (「既知の互換性エラーまたは問題が見つかりませんでした。」など)。

checksPerformed

JSON オブジェクトの配列。自動的にチェックされた個々のアップグレードの問題 (削除された関数の使用など) ごとに 1 つずつ。各 JSON オブジェクトには、次のキーと値のペアがあります:

id

一意の文字列であるチェックの ID。

title

チェックの短い説明。

status

チェックが正常に実行された場合は「OK」、それ以外の場合は「ERROR」。

description

アドバイスを組み込むチェック (使用可能な場合) の詳細な説明、またはチェックの実行に失敗した場合はエラーメッセージ。

documentationLink

使用可能な場合は、詳細情報またはアドバイスを含むドキュメントへのリンク。

detectedProblems

チェックの結果として見つかったエラー、警告または通知を表す JSON オブジェクトの配列 (空の可能性があります)。各 JSON オブジェクトには、次のキーと値のペアがあります:

level: メッセージレベル。エラー、警告または通知のいずれか。
dbObject: メッセージが関連するデータベースオブジェクトを識別する文字列。
description: 使用可能な場合は、データベースオブジェクトに関する問題の特定の説明を含む文字列。

manualChecks

JSON オブジェクトの配列で、アップグレードパスに関連し、手動でチェックする必要がある個々のアップグレードの問題 (たとえば、MySQL 8.0 でのデフォルトの認証プラグインの変更) ごとに使用されます。各 JSON オブジェクトには、次のキーと値のペアがあります:

id: 一意の文字列である手動チェックの ID。
title: 手動チェックの簡単な説明。
description: 手動チェックの詳細な説明と、情報およびアドバイス。
documentationLink: 使用可能な場合は、詳細情報またはアドバイスを含むドキュメントへのリンク。

PREV HOME UP NEXT