PDF (美式信紙) - 2.3Mb
PDF (A4) - 2.3Mb
util.checkForServerUpgrade() 函數是一個升級檢查工具，可讓您驗證 MySQL 伺服器執行個體是否已準備好進行升級。您可以選取計畫升級的目標 MySQL 伺服器版本，範圍從第一個 MySQL 伺服器 8.0 一般可用性 (GA) 版本 (8.0.11) 到與目前 MySQL Shell 版本號碼相符的 MySQL 伺服器版本號碼。升級檢查工具會執行與指定目標版本相關的自動檢查，並建議您進一步執行相關的手動檢查。
您可以使用升級檢查工具來檢查 MySQL 5.7 伺服器執行個體，以及 MySQL 8.x 版本系列中另一個 GA 狀態版本的 MySQL 8.x 伺服器執行個體，以找出升級的相容性錯誤和問題。如果您在未指定 MySQL 伺服器執行個體的情況下叫用 checkForServerUpgrade()，則會檢查目前連線至全域工作階段的執行個體。若要查看目前連線的執行個體，請發出 \status 命令。
注意
升級檢查工具不支援檢查 MySQL 5.7 之前的 MySQL 伺服器執行個體。
MySQL 伺服器僅支援從 5.7 開始的 GA 版本之間的升級。不支援從非 GA 版本升級。如需有關支援升級路徑的詳細資訊，請參閱升級路徑。
升級檢查工具可以檢查伺服器執行個體的組態檔 (my.cnf 或 my.ini)。此工具會檢查組態檔中定義但在目標 MySQL 伺服器版本中已移除的任何系統變數，以及未在組態檔中定義且在目標 MySQL 伺服器版本中將具有不同預設值的任何系統變數。對於這些檢查，當您叫用 checkForServerUpgrade() 時，您必須提供組態檔的檔案路徑。
升級檢查工具可以文字格式 (預設) 或 JSON 格式產生其輸出，JSON 格式可能更容易剖析和處理，以便在 DevOps 自動化中使用。
升級檢查工具可以使用 X 通訊協定連線或傳統 MySQL 通訊協定連線，使用 TCP 或 Unix Socket 運作。您可以事先建立連線，或將其指定為函數的引數。此工具一律會建立新的工作階段以連線至伺服器，因此不會影響 MySQL Shell 全域工作階段。
用來執行升級檢查工具的使用者帳戶需要 RELOAD、PROCESS 和 SELECT 權限。
升級檢查工具具有下列簽章
checkForServerUpgrade (ConnectionData connectionData, Dictionary options)這兩個引數都是選用的。第一個引數提供連線資料 (如果連線尚不存在)，第二個引數是一個字典，您可以用來指定下列選項
-
password 用來執行升級檢查工具的使用者帳戶密碼。您可以使用此字典選項或作為連線詳細資料的一部分來提供密碼。如果您未提供密碼，則此工具會在連線至伺服器時提示您輸入密碼。
-
targetVersion 您計畫升級的目標 MySQL 伺服器版本。您可以指定從 8.0.11 (第一個 MySQL 伺服器 8.0 GA 版本) 到與您使用的 MySQL Shell 版本號碼相同的 MySQL 伺服器版本的任何版本。如果您指定簡短版本號碼 (例如 8.0) 或省略
targetVersion選項，則此工具會檢查是否要升級至與您使用的 MySQL Shell 版本號碼相符的 MySQL 伺服器版本號碼。-
configPath 您要檢查的 MySQL 伺服器執行個體的
my.cnf或my.ini組態檔的本機路徑，例如，C:\ProgramData\MySQL\MySQL Server 8.1\my.ini。如果您省略檔案路徑，且升級檢查工具需要執行需要組態檔的檢查，則該檢查會失敗，並顯示訊息告知您必須指定檔案路徑。-
outputFormat 傳回升級檢查工具輸出的格式。如果您省略此選項，則預設值為文字格式 (
TEXT)。如果您指定JSON，則會改為傳回格式正確的 JSON 輸出，格式列於來自升級檢查工具的 JSON 輸出中。-
include -
要執行的升級檢查之逗號分隔清單。只會執行指定的檢查。如果檢查同時定義於
include和exclude清單中，則會傳回錯誤。例如
"include": ["invalidPrivileges", "removedSysVars", "sysVarsNewDefaults"]請參閱工具檢查。
-
exclude -
要忽略的升級檢查之逗號分隔清單。如果檢查同時定義於 include 和 exclude 清單中，則會傳回錯誤。
例如
"exclude": ["invalidPrivileges", "removedSysVars", "sysVarsNewDefaults"]請參閱工具檢查。
-
list -
傳回包含和排除在目前組態中的所有檢查之清單、檢查的描述以及檢查適用的版本。
例如
{"list": true, "targetVersion": "8.4.0"}請參閱工具檢查。
例如，下列命令會驗證，然後檢查目前連線至全域工作階段的 MySQL 伺服器執行個體，並以文字格式輸出
mysqlsh> \status
\status
MySQL Shell version 8.1.0-commercial
...
Server version: 8.1.0-commercial MySQL Enterprise Server - Commercial
...
mysqlsh> util.checkForServerUpgrade()下列命令會檢查 URI user@example.com:3306 上的 MySQL 伺服器是否升級至 MySQL 伺服器版本 8.1.0。使用者密碼和組態檔路徑會以選項字典的一部分提供，而輸出會以預設文字格式傳回
mysqlsh> util.checkForServerUpgrade('user@example.com:3306',
{"password":"password", "targetVersion":"8.1.0", "configPath":"C:/ProgramData/MySQL/MySQL Server 8.0/my.ini"})下列命令會檢查同一部 MySQL 伺服器是否升級至與目前 MySQL Shell 版本號碼相符的 MySQL 伺服器版本號碼 (預設值)，並傳回 JSON 輸出以供進一步處理
mysqlsh> util.checkForServerUpgrade('user@example.com:3306',
{"password":"password", "outputFormat":"JSON", "configPath":"C:/ProgramData/MySQL/MySQL Server 8.0/my.ini"})您可以使用 mysqlsh 命令介面從命令列啟動升級檢查工具。如需有關此語法的資訊，請參閱第 5.8 節，「API 命令列整合」。下列範例會檢查 MySQL 伺服器是否升級至版本 8.0.27，並傳回 JSON 輸出
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下列範例使用 Unix Socket 連線，並顯示從命令列叫用工具的舊格式，該格式仍然有效
./bin/mysqlsh --socket=/tmp/mysql.sock --user=user -e "util.checkForServerUpgrade()"若要取得升級檢查工具的說明，請發出
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://mysqldev.dev.org.tw/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://mysqldev.dev.org.tw/doc/refman/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:
https://mysqldev.dev.org.tw/doc/refman/8.0/en/upgrading-from-previous-series.html#upgrade-caching-sha2-password-compatibility-issues
https://mysqldev.dev.org.tw/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 版本之前，需要進行變更。
當您已進行必要的變更以清除報表的錯誤計數時，您也應該考慮進行進一步變更以移除警告。這些組態改善功能會讓伺服器執行個體更符合目標版本的相容性。不過，伺服器執行個體可以在不移除警告的情況下成功升級。
如此範例所示，升級檢查工具也可能會提供建議和指示，以供進一步進行相關檢查 (無法自動執行，您應該手動進行)，這些檢查會評等為警告或注意 (資訊) 層級。
升級檢查會執行下列檢查
oldTemporal：檢查是否使用已棄用的時間類型。routineSyntax：檢查常式語法是否存在與保留關鍵字的衝突。請參閱關鍵字和保留字。reservedKeywords：檢查資料庫物件名稱是否與保留關鍵字衝突。請參閱關鍵字和保留字。utf8mb3：檢查是否使用 utf8mb3 字元集。雖然支援 utf8mb3，但建議使用 utf8mb4 以獲得更佳的 Unicode 支援。請參閱utf8mb3 字元集（3 位元組 UTF-8 Unicode 編碼）。mysqlSchema：檢查mysql綱要中的資料表名稱是否與目標版本中的資料表衝突。nonNativePartitioning：檢查是否使用非原生分割的已分割資料表。foreignKeyLength：檢查外鍵限制名稱是否超過 64 個字元。請參閱準備您的安裝以進行升級。maxdbSqlModeFlags：檢查是否使用已過時的sql_mode旗標，MAXDB。obsoleteSqlModeFlags：檢查是否使用已過時的sql_mode旗標。enumSetElementLength：檢查ENUM/SET資料行定義是否包含超過 255 個字元的元素。partitionedTablesInSharedTablespaces：檢查共用表空間中是否有已分割的資料表。circularDirectory：檢查表空間資料檔案路徑中是否有循環目錄參照。removedFunctions：檢查在目標 MySQL 版本中移除的函式。groupbyAscSyntax：檢查GROUP BY ASC或DESC語法。removedSysLogVars：檢查用於設定系統記錄的舊系統變數。-
sysvar：執行下列檢查檢查在目標版本中具有不同預設值的系統變數。
檢查系統變數是否具有有效的值。
檢查來源中使用但在目標版本中已棄用或移除的系統變數。表示系統變數在來源上設定為非預設值。
zeroDates：檢查零日期、日期時間和時間戳記值。schemaInconsistency：檢查因檔案移除或損毀而導致的綱要不一致。ftsInTablename：檢查資料表名稱是否包含FTS，這在 MySQL 8.0 或更高版本中不受支援。engineMixup：檢查 InnoDB 識別但屬於不同引擎的資料表。oldGeometryTypes：檢查在 MySQL 5.6 中建立的空間資料行。checkTableCommand：檢查CHECK TABLE命令回報的問題。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：檢查參照非唯一和部分索引的外鍵。
當您使用 outputFormat 字典選項選擇 JSON 輸出時，升級檢查程式公用程式傳回的 JSON 物件具有下列索引鍵值組
- serverAddress
MySQL Shell 連線到所檢查之 MySQL 伺服器執行個體的的主機名稱和連接埠號碼。
- serverVersion
所檢查伺服器執行個體的偵測到的 MySQL 版本。
- targetVersion
Target MySQL version for the upgrade checks.
- errorCount
公用程式找到的錯誤數。
- warningCount
公用程式找到的警告數。
- noticeCount
公用程式找到的注意事項數。
- summary
摘要陳述式的文字，該陳述式將在文字輸出結束時提供（例如，「未找到已知的相容性錯誤或問題。」）。
- checksPerformed
-
JSON 物件的陣列，每個物件對應一個自動檢查的個別升級問題（例如，使用移除的函式）。每個 JSON 物件都有下列索引鍵值組
- id
檢查的 ID，這是唯一的字串。
- title
檢查的簡短說明。
- status
如果檢查成功執行則為「OK」，否則為「ERROR」。
- description
檢查的長說明（如果有的話），包含建議，如果檢查無法執行則包含錯誤訊息。
- documentationLink
如果有的話，則為具有其他資訊或建議的文件連結。
- detectedProblems
-
JSON 物件的陣列（可能為空），表示因檢查結果發現的錯誤、警告或注意事項。每個 JSON 物件都有下列索引鍵值組
- level
訊息層級，為「Error」、「Warning」或「Notice」其中之一。
- dbObject
識別訊息相關的資料庫物件的字串。
- description
如果有的話，則為包含資料庫物件之特定問題說明的字串。
- dbObjectType
dbObject的類型。這可以是下列其中之一：綱要、資料表、檢視、資料行、索引、外鍵、常式、事件、觸發程序、系統變數、使用者、表空間或外掛程式。
- manualChecks
-
JSON 物件的陣列，每個物件對應一個與您的升級路徑相關且需要手動檢查的個別升級問題（例如，MySQL 8.0 中預設驗證外掛程式的變更）。每個 JSON 物件都有下列索引鍵值組
- id
手動檢查的 ID，這是唯一的字串。
- title
手動檢查的簡短說明。
- description
手動檢查的長說明，其中包含資訊和建議。
- documentationLink
如果有的話，則為具有其他資訊或建議的文件連結。