AWS AmazonRDS documentation change

Service: AmazonRDS · 2025-06-10 · Documentation low

File: AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.upgrade-prechecks.descriptions.md

Summary

Added a new precheck (auroraUpgradeCheckForInvalidUtf8mb3ColumnComments) to detect invalid utf8mb3 column comments before upgrading to MySQL 8.0.

Security assessment

The precheck addresses compatibility issues with MySQL 8.0's stricter metadata validation but does not directly relate to security vulnerabilities or security features. The focus is on preventing upgrade failures due to encoding issues.

Diff

diff --git a/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.upgrade-prechecks.descriptions.md b/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.upgrade-prechecks.descriptions.md
index f7fc2e8e9..ee849f4dd 100644
--- a//AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.upgrade-prechecks.descriptions.md
+++ b//AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.upgrade-prechecks.descriptions.md
@@ -1224,0 +1225,2 @@ The following prechecks are specific to Aurora MySQL:
+  * auroraUpgradeCheckForInvalidUtf8mb3ColumnComments
+
@@ -1915,0 +1918,61 @@ If you encounter any errors with this precheck, open a case with [AWS Support](h
+**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.
+
+The most common cause of this issue is the presence of non-BMP (Basic Multilingual Plane) characters in column comments. Non-BMP characters require 4-byte UTF-8 encoding (utf8mb4), but utf8mb3 only supports 3-byte sequences, which cannot represent these characters.
+
+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.
+