AWS AmazonRDS documentation change
Summary
Added four new prechecks (auroraUpgradeCheckForInvalidUtf8mb3CharacterStringInViews, auroraUpgradeCheckForInvalidUtf8mb3ColumnComments, auroraUpgradeCheckForInvalidUtf8mb3IndexComments, auroraUpgradeCheckForInvalidUtf8mb3TableComments) with detailed documentation about MySQL 8.0 upgrade compatibility requirements for metadata encoding. Removed redundant auroraUpgradeCheckForInvalidUtf8mb3ColumnComments section that was replaced by more detailed content.
Security assessment
The changes document upgrade compatibility checks for utf8mb3 encoding requirements in MySQL 8.0 metadata. While important for successful upgrades, there is no evidence these changes address security vulnerabilities or weaknesses - they prevent upgrade failures due to MySQL's stricter encoding validation. The documentation focuses on compatibility rather than security protections.
Diff
diff --git a/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.upgrade-prechecks.descriptions.md b/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.upgrade-prechecks.descriptions.md index ee849f4dd..8e9a11730 100644 --- a//AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.upgrade-prechecks.descriptions.md +++ b//AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.upgrade-prechecks.descriptions.md @@ -1210,0 +1211,8 @@ The following prechecks are specific to Aurora MySQL: + * auroraUpgradeCheckForInvalidUtf8mb3CharacterStringInViews + + * auroraUpgradeCheckForInvalidUtf8mb3ColumnComments + + * auroraUpgradeCheckForInvalidUtf8mb3IndexComments + + * auroraUpgradeCheckForInvalidUtf8mb3TableComments + @@ -1225,2 +1232,0 @@ The following prechecks are specific to Aurora MySQL: - * auroraUpgradeCheckForInvalidUtf8mb3ColumnComments - @@ -1581,0 +1588,247 @@ This precheck applies only to Aurora MySQL version 3.03.0 and lower. If you enco +**auroraUpgradeCheckForInvalidUtf8mb3CharacterStringInViews** + + +**Precheck level: Error** + +**Check for invalid utf8mb3 characters in view definition** + +This precheck identifies views that contain comments with invalid `utf8mb3` character encoding. In MySQL 8.0, stricter validation is applied to character encoding in metadata, including view comments. If any view definition contains characters that are not valid in the `utf8mb3` character set, the upgrade fails. + +To resolve this issue, modify the view definition to remove or replace any non-BMP characters before you attempt the upgrade. + +**Example output:** + + + { + "id": "auroraUpgradeCheckForInvalidUtf8mb3CharacterStringInViews", + "title": "Check for invalid utf8mb3 character string.", + "status": "OK", + "description": "Definition of following view(s) has/have invalid utf8mb3 character string.", + "detectedProblems": [ + { + "level": "Error", + "dbObject": "precheck.utf8mb3_invalid_char_view", + "description": "Definition of view precheck.utf8mb3_invalid_char_view contains an invalid utf8mb3 character string. This is due to https://bugs.mysql.com/bug.php?id=110177. To fix the inconsistency, we recommend you to modify the view definition to not use non-BMP characters and try the upgrade again." + } + ] + }, + +The precheck reports that the `utf8mb3_invalid_char_view` view definition contains invalid `utf8mb3` characters in its definition. + +To resolve this issue, identify the view that contains the unsupported characters and update the comments. First, examine the view structure and identify comments. + + + MySQL> SHOW CREATE VIEW precheck.utf8mb3_invalid_char_view\G + *************************** 1. row *************************** + View: utf8mb3_invalid_char_view + Create View: CREATE ALGORITHM=UNDEFINED DEFINER=`admin`@`%` SQL SECURITY DEFINER VIEW `utf8mb3_invalid_char_view` AS select 'This row contains a dolphin 🐬' AS `message` + character_set_client: utf8 + collation_connection: utf8_general_ci + 1 row in set, 1 warning (0.00 sec) + +Once you've identified the view that contains the error, replace the view with the `CREATE OR REPLACE VIEW` statement. + + + MySQL> CREATE OR REPLACE VIEW precheck.utf8mb3_invalid_char_view AS select 'This view definition to not use non-BMP characters' AS message; + +After updating all view definitions that contain unsupported characters, the precheck passes and the upgrade can proceed. + + + { + "id": "auroraUpgradeCheckForInvalidUtf8mb3ColumnComments", + "title": "Check for invalid utf8mb3 column comments.", + "status": "OK", + "detectedProblems": [] + } + +**auroraUpgradeCheckForInvalidUtf8mb3ColumnComments** + + +**Precheck level: Error** + +**Check for invalid utf8mb3 column comments** + +This precheck identifies tables that contain column comments with invalid `utf8mb3` character encoding. In MySQL 8.0, stricter validation is applied to character encoding in metadata, including column comments. If any column comments contain characters that are not valid in the utf8mb3 character set, the upgrade will fail. + +To resolve this issue, you must modify the column comments to remove or replace any non-BMP characters before attempting the upgrade. You can use the `ALTER TABLE` statement to update the column comments. + +**Example output:** + + + { + "id": "auroraUpgradeCheckForInvalidUtf8mb3ColumnComments", + "title": "Check for invalid utf8mb3 column comments.", + "status": "OK", + "description": "Following table(s) has/have invalid utf8mb3 comments on the column/columns.", + "detectedProblems": [ + { + "level": "Error", + "dbObject": "test.t2", + "description": "Table test.t2 has invalid utf8mb3 comments in it's column/columns. This is due to non-BMP characters in the comment field. To fix the inconsistency, we recommend you to modify comment fields to not use non-BMP characters and try the upgrade again." + } + ] + } + +The precheck reports that the `test.t2` table contains invalid `utf8mb3` characters in one or more column comments, specifically due to the presence of non-BMP characters. + +To resolve this issue, you can identify the problematic columns and update their comments. First, examine the table structure to identify columns with comments: + + + mysql> SHOW CREATE TABLE test.t2\G + +Once you've identified the columns with problematic comments, update them using the `ALTER TABLE` statement. For example: + + + mysql> ALTER TABLE test.t2 MODIFY COLUMN column_name data_type COMMENT 'Updated comment without non-BMP characters'; + +Alternatively, you can remove the comment entirely: + + + mysql> ALTER TABLE test.t2 MODIFY COLUMN column_name data_type COMMENT ''; + +After updating all problematic column comments, the precheck will pass and the upgrade can proceed: + + + { + "id": "auroraUpgradeCheckForInvalidUtf8mb3ColumnComments", + "title": "Check for invalid utf8mb3 column comments.", + "status": "OK", + "detectedProblems": [] + } + +###### Note + +Before modifying column comments, ensure that any application code or documentation that relies on these comments is updated accordingly. Consider migrating to the utf8mb4 character set for better Unicode support if your application requires non-BMP characters. + +**auroraUpgradeCheckForInvalidUtf8mb3IndexComments** + + +**Precheck level: Error** + +**Check for invalid utf8mb3 index comments** + +This precheck identifies tables that contain index comments with invalid `utf8mb3` character encoding. In MySQL 8.0, stricter validation is applied to character encoding in metadata, including index comments. If any index comments contain characters that are not valid in the `utf8mb3` character set, the upgrade fails. + +To resolve this issue, you must modify the index comments to remove or replace any non-BMP characters before attempting the upgrade. + +**Example output:** + + + { + "id": "auroraUpgradeCheckForInvalidUtf8mb3IndexComments", + "title": "Check for invalid utf8mb3 index comments.", + "status": "OK", + "description": "Following table(s) has/have invalid utf8mb3 comments on the index.", + "detectedProblems": [ + { + "level": "Error", + "dbObject": "precheck.utf8mb3_tab_index_comment", + "description": "Table precheck.utf8mb3_tab_index_comment has invalid utf8mb3 comments in it's index. This is due to https://bugs.mysql.com/bug.php?id=110177. To fix the inconsistency, we recommend you to modify comment fields to not use non-BMP characters and try the upgrade again." + } + ] + }, + +The precheck reports that the `utf8mb3_tab_index_comment` table contains invalid `utf8mb3` characters in one or more column comments, specifically due to the presence of non-BMP characters. + +To resolve this issue, first, examine the table structure to identify the index with problematic comments. + + + MySQL> SHOW CREATE TABLE precheck.utf8mb3_tab_index_comment\G + *************************** 1. row *************************** + Table: utf8mb3_tab_index_comment + Create Table: CREATE TABLE `utf8mb3_tab_index_comment` ( + `id` int(11) DEFAULT NULL, + `name` varchar(100) DEFAULT NULL, + KEY `idx_name` (`name`) COMMENT 'Name index 🐬' + ) ENGINE=InnoDB DEFAULT CHARSET=utf8 + 1 row in set (0.01 sec) + +Once you identify the index that contains comments that use unsupported characters, drop and recreate the index. + +###### Note + +Dropping and recreating a table index can lead to downtime. We recommend that you plan and schedule this operation during maintenance. + + + MySQL> ALTER TABLE precheck.utf8mb3_tab_index_comment DROP INDEX idx_name; + MySQL> ALTER TABLE precheck.utf8mb3_tab_index_comment ADD INDEX idx_name(name); + +The following example shows another way to recreate the index. + + + MySQL> ALTER TABLE utf8mb3_tab_index_comment DROP INDEX idx_name, ADD INDEX idx_name (name) COMMENT 'Updated comment without non-BMP characters'; + +After you remove or update all unsupported index comments, the precheck passes and the upgrade can proceed. + + + { + "id": "auroraUpgradeCheckForInvalidUtf8mb3IndexComments", + "title": "Check for invalid utf8mb3 index comments.", + "status": "OK", + "detectedProblems": [] + }, +