Amazon RDS for MySQL のアップグレード前のチェックの失敗を解決するにはどうすればよいですか?

簡単な説明

DB インスタンスでアップグレード前のチェックに失敗すると、Amazon RDS for MySQL のバージョンアップグレードは停止します。Amazon RDS では、互換性がないことが検出されると、ログファイルが出力され、失敗した事前チェックの詳細を確認できます。

注: MySQL データベースと Amazon RDS では、どちらにもさまざまな事前チェックが組み込まれています。MySQL 5.7 より前のバージョンのアップグレードでは、事前チェックは実行されません。MySQL 5.6 から MySQL 5.7 へのアップグレードでは、事前チェックは孤立テーブルの検出とテーブルを再構築するための十分なストレージ容量に限られます。

MySQL 5.7.x から MySQL 8.0.x へのアップグレードを実行すると、Amazon RDS と Amazon Aurora MySQL 互換エディションでは、自動的に事前チェックが行われます。事前チェックにより、アップグレードに影響する可能性があるデータの互換性がないことが検出されます。事前チェックは、バージョンアップグレード中の予定外のダウンタイムを最小限に抑えるように設計されています。

このバージョンアップグレード中にアップグレード前のチェックが失敗した場合は、Amazon RDS が生成する PrePatchCompatibility ログファイルを確認してください。PrePatchCompatibility ログファイルは、Amazon RDS コンソールの [ログとイベント] で確認できます。次に、一覧表示された非互換性の問題の詳細を確認し、問題を修正します。ほとんどの場合、ログエントリには、互換性がないことを修正する方法に関する Amazon RDS for MySQL のドキュメントへのリンクが含まれます。

解決方法

注: AWS コマンドラインインターフェイス (AWS CLI) のコマンド実行中にエラーが発生した場合は、最新の AWS CLI バージョンを使用していることを確認してください。

アップグレード前のチェック失敗のメッセージを確認して、アップグレードが失敗した理由を確認します。次の例をご覧ください:

Executing Compatibility Checks for the MySQL server at localhost:3306.
Source Version: 5.7.40-log - Source distribution, Target Version: 8.0.32.

1) Usage of old temporal type
No issues found.
2) Usage of db objects with names conflicting with new reserved keywords
No issues found.
....
Errors: 1
Warnings: 0
Database Objects Affected: 14
----------------------- END OF LOG ----------------------

メッセージに特定のエラー、警告、通知レベルのメッセージがないか確認します。以下のリストを参照して、発生したエラー、警告、または通知を特定し、それに応じてトラブルシューティングを行います:

ERROR : Correct these issues before upgrading to avoid compatibility issues.
WARNING : No fatal errors were found that would prevent an upgrade, but some potential issues were detected.
NOTICE : No known compatibility errors or issues were found. But you can check the NOTICE Level error logs.

1) Usage of old temporal type : ERROR
2) Usage of db objects with names conflicting with new reserved keywords : WARNING
3) Usage of utf8mb3 charset : NOTICE
4) Table names in the mysql schema conflicting with new tables in 8.0 : ERROR
5) Partitioned tables using engines with non native partitioning : ERROR
6) Foreign key constraint names longer than 64 characters : ERROR
7) Usage of obsolete MAXDB sql_mode flag : WARNING
8) Usage of obsolete sql_mode flags : NOTICE
9)  ENUM/SET column definitions containing elements longer than 255 characters : ERROR
10) Usage of partitioned tables in shared tablespaces : ERROR
11) Circular directory references in tablespace data file paths : ERROR
12) Usage of removed functions : ERROR
13) Usage of removed GROUP BY ASC/DESC syntax : ERROR
14) Removed system variables for error logging to the system log configuration : ERROR
15) Removed system variables : ERROR
16) System variables with new default values : WARNING
17) Schema inconsistencies resulting from file removal or corruption : ERROR
18) Issues reported by 'check table x for upgrade' command : ERROR or WARNING or NOTICE
19) The definer column for mysql.events cannot be null or blank. : ERROR
20) Tables with dangling FULLTEXT index reference : ERROR
21) Routines with deprecated keywords in definition : ERROR
22) DB instance must have enough free disk space : ERROR
23) Creating indexes larger than 767 bytes on tables with redundant row format might cause the tables to be inaccessible. : WARNING
24) The tables with redundant row format can't have an index larger than 767 bytes. : ERROR
25) Column definition mismatch between InnoDB Data Dictionary and actual table definition. : ERROR

AWS CLI を使用して以下のようなコマンドを実行し、ログファイルを一覧表示してデータをダウンロードします:

$ aws rds describe-db-log-files --db-instance-identifier <DB identifier> --query '*[].[LogFileName]' --output text

Sample:
[root@ip-x-x-x-x ec2-user]# aws rds describe-db-log-files --db-instance-identifier testinstance --query '*[].[LogFileName]' --output text
PrePatchCompatibility.log
error/mysql-error.log
error/mysql-error-running.log
error/mysql-error-running.log.2023-05-06.3
error/mysql-error-running.log.2023-05-09.4
error/mysql-error-running.log.2023-05-10.3
error/mysql-error-running.log.2023-05-12.19
mysqlUpgrade

Command to download the file:
$ aws rds download-db-log-file-portion --db-instance-identifier <DB identifier> \
--log-file-name PrePatchCompatibility.log --starting-token 0 \
--output text > <LogFileName to save a copy>

Sample:
$ aws rds download-db-log-file-portion --db-instance-identifier testinstance \
--log-file-name PrePatchCompatibility.log --starting-token 0 \
--output text > PrePatchCompatibilityCopy.log

詳細については、MySQL のドキュメント「MySQL 8.0 にアップグレードしますか? こちらが把握しておくべきこととなります...」を参照してください。

注: メジャーバージョンのアップグレードを実行する前に DB インスタンスをテストするのがベストプラクティスです。