MySQL :: MySQL Shell 9.0 :: 6.9 標記元數據

版本 9.0

8.4 目前
8.0

8.0 日文

MySQL Shell 9.0 / MySQL AdminAPI / 標記元數據

6.9 標記元數據

可設定的標記架構可供使用，以允許使用額外資訊來標記 InnoDB Cluster、InnoDB ClusterSet 或 InnoDB ReplicaSet 的元數據。標記可將自訂的鍵值組與 Cluster、ReplicaSet 或執行個體建立關聯。標記已保留供 MySQL Router 使用，以讓相容的 MySQL Router 能夠支援從應用程式隱藏執行個體。下列標記保留供此用途使用

_hidden 指示 MySQL Router：從用戶端應用程式的可能目的地清單中排除執行個體。
_disconnect_existing_sessions_when_hidden：指示路由器中斷與標記為隱藏的執行個體的現有連線。

如需更多資訊，請參閱從路由中移除執行個體。

此外，標記架構是使用者可設定的。自訂標記可以包含任何 ASCII 字元，並提供 namespace，其作用如同可以與叢集、ReplicaSet 或其特定執行個體建立關聯的字典鍵值組。標記值可以是任何 JSON 值。此設定可讓您在元數據之上新增自己的屬性。

顯示標記

Cluster.options() 作業會顯示有關指派給個別叢集執行個體以及叢集本身的標記資訊。例如，指派給 myCluster 的 InnoDB Cluster 可以顯示

mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [
                {
                    "option": "_disconnect_existing_sessions_when_hidden",
                    "value": true
                },
                {
                    "option": "_hidden",
                    "value": false
                }
            ],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": [
                {
                    "option": "location:",
                    "value": "US East"
                }
            ]
        }
    }
}

此叢集有一個名為 location 的全域標記，其值為 US East，並且執行個體 ic-1 已被標記。

在叢集執行個體上設定標記

您可以在執行個體層級設定標記，這可讓您例如將執行個體標記為不可用，以便應用程式和路由器將其視為離線。使用 Cluster.setInstanceOption(instance, option, value) 作業來設定執行個體的標記值。

instance 引數是目標執行個體的連線字串。option 引數必須是格式為 namespace:option 的字串。value 參數是應指派給指定 namespace 中 option 的值。如果值為 null，則會從指定 namespace 中移除 option。對於屬於叢集的執行個體，setInstanceOption() 作業僅接受 tag namespace。任何其他 namespace 都會導致 ArgumentError。

例如，若要使用 JavaScript 將標記 test 設定為 true 在 myCluster 執行個體 ic-1 上，請發出

mysql-js> myCluster.setInstanceOption("icadmin@ic-1:3306", "tag:test", true);

或使用 Python 將標記 test 設定為 true 在 myCluster 執行個體 ic-1 上，請發出

mysql-py> myCluster.set_instance_option("icadmin@ic-1:3306", "tag:test", True);

從路由中移除執行個體

當 AdminAPI 和 MySQL Router 一起運作時，它們支援特定的標記，可讓您將執行個體標記為隱藏並將其從路由中移除。然後，MySQL Router 會從路由目的地候選清單中排除此類標記的執行個體。此功能可讓您安全地讓伺服器執行個體離線，以便應用程式和 MySQL Router 忽略它。例如，當您執行維護工作時，例如伺服器升級或組態變更。

當 _hidden 標記設定為 true 時，這會指示 MySQL Router 從用戶端應用程式的可能目的地清單中排除執行個體。執行個體保持連線狀態，但不會將新連入的連線路由至該執行個體。_disconnect_existing_sessions_when_hidden 標記會控制如何關閉與執行個體的現有連線。此標記假設為 true，並且指示任何針對 InnoDB Cluster、InnoDB ClusterSet 或 InnoDB ReplicaSet 啟動的 MySQL Router 執行個體在 _hidden 標記為 true 時中斷與執行個體的任何現有連線。

當 _disconnect_existing_sessions_when_hidden 為 false 時，如果 _hidden 為 true，則不會關閉與執行個體的任何現有用戶端連線。保留的 _hidden 和 _disconnect_existing_sessions_when_hidden 標記特定於執行個體，且不能在叢集層級使用。

警告

當啟用 use_gr_notifications MySQL Router 選項時，其預設為 60 秒。這表示當您設定標記時，MySQL Router 最多需要 60 秒才能偵測到變更。若要減少等待時間，請將 use_gr_notifications 變更為較低的值。

例如，假設您想要從路由目的地中移除屬於指派給 myCluster 之 InnoDB Cluster 的 ic-1 執行個體。使用 setInstanceOption() JavaScript 作業來啟用 _hidden 和 _disconnect_existing_sessions_when_hidden 標記

mysql-js> myCluster.setInstanceOption("icadmin@ic-1:3306", "tag:_hidden", true);

或使用 set_instance_option() Python 作業來啟用 _hidden 和 _disconnect_existing_sessions_when_hidden 標記

			mysql-js> myCluster.set_instance_option("icadmin@ic-1:3306", "tag:_hidden", true);

您可以藉由檢查選項來驗證元數據中的變更。例如，對 ic-1 所做的變更會在選項中顯示為

mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [
                {
                    "option": "_disconnect_existing_sessions_when_hidden",
                    "value": true
                },
                {
                    "option": "_hidden",
                    "value": true
                }
            ],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": []
        }
    }
}

您可以藉由檢視記錄檔來驗證 MySQL Router 是否已偵測到元數據中的變更。已偵測到對 ic-1 所做變更的 MySQL Router 將會顯示類似如下的變更

2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700] Potential changes detected in cluster 'testCluster' after metadata refresh
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700] view_id = 4, (3 members)
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700]     ic-1:3306 / 33060 - mode=RW
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700]     ic-1:3306 / 33060 - mode=RO
2020-07-03 16:32:16 metadata_cache INFO [7fa9d164c700]     ic-1:3306 / 33060 - mode=RO hidden=yes disconnect_when_hidden=yes
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_x_ro listening on 64470 got request to disconnect invalid connections: metadata change
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_x_rw listening on 64460 got request to disconnect invalid connections: metadata change
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_rw listening on 6446 got request to disconnect invalid connections: metadata change
2020-07-03 16:32:16 routing INFO [7fa9d164c700] Routing routing:testCluster_ro listening on 6447 got request to disconnect invalid connections: metadata change

若要將執行個體重新上線，請使用 setInstanceOption() 作業來移除標記，而 MySQL Router 會自動將執行個體新增回路由目的地，並且應用程式會使其上線。例如

mysql-js> myCluster.setInstanceOption(icadmin@ic-1:3306, "tag:_hidden", false);

再次檢查選項來驗證元數據中的變更

mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [
                {
                    "option": "_disconnect_existing_sessions_when_hidden",
                    "value": true
                },
                {
                    "option": "_hidden",
                    "value": false
                }
            ],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": []
        }
    }
}

您也可以使用下列命令的輸出中的屬性 hiddenFromRouter 來檢視成員上的 _hidden 狀態

Cluster.status()
Cluster.describe()
ReplicaSet.status()

對於使用 _hidden 元數據標記從 MySQL Router 流量隱藏的任何成員，此屬性為 true。

在叢集上設定標記

Cluster.setOption(option, value) 作業可讓您變更整個叢集的命名空間選項值。option 引數必須是格式為 namespace:option 的字串。

value 參數是要指派給指定 namespace 中 option 的值。如果值為 null，則會從指定 namespace 中移除 option。對於叢集，setOption() 作業接受 tag namespace。任何其他 namespace 都會導致 ArgumentError。

提示

在叢集層級設定的標記不會覆寫在執行個體層級設定的標記。您無法使用 Cluster.setOption() 來移除在執行個體層級設定的所有標記。

並非要求所有執行個體都必須上線，只要求叢集具有仲裁。若要將指派給 myCluster 的 InnoDB Cluster 標記為 location 標記設定為 US East，請在 JavaScript 中發出下列指令

mysql-js> myCluster.setOption("tag:location", "US East")
mysql-js> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": [
                {
                    "option": "location:",
                    "value": "US East"
                }
            ]
        }
    }
}

或在 Python 中發出下列指令

mysql-py> myCluster.set_option("tag:location", "US East")
mysql-pys> myCluster.options()
{
    "cluster": {
        "name": "test1",
        "tags": {
            "ic-1:3306": [],
            "ic-2:3306": [],
            "ic-3:3306": [],
            "global": [
                {
                    "option": "location:",
                    "value": "US East"
                }
            ]
        }
    }
}

從叢集移除標記

若要從叢集移除標記，請使用 Cluster.setOption(option, value) 作業，在 JavaScript 中使用 null 值，在 Python 中使用 None 值。

若要從指派給 myCluster 的 InnoDB Cluster 中移除帶有 location 標籤的標籤，請在 JavaScript 中執行以下操作

mysql-js> myCluster.setOption("tag:location", null)

或使用 Python

mysql-js> myCluster.set_option("tag:location", None)

使用者定義標籤

AdminAPI 支援 tag 命名空間，您可以在其中儲存與特定 Cluster、ReplicaSet 或執行個體相關聯的鍵值對資訊。tag 命名空間下的選項不受限制，這表示您可以標記任何您選擇的資訊，只要它是有效的 MySQL ASCII 識別符號即可。

您可以使用任何名稱和值作為標籤，只要名稱遵循以下語法：_ 或字母，後跟字母數字和 _ 字元。

namespace 選項是一個以冒號分隔的字串，格式為 namespace:option，其中 namespace 是命名空間的名稱，而 option 是實際的選項名稱。您可以在執行個體層級、或在 Cluster 或 ReplicaSet 層級設定和移除標籤。

標籤名稱可以具有任何值，只要它以字母或底線開頭，並且可以選擇性地後跟字母數字和 _ 字元，例如，^[a-zA-Z_][0-9a-zA-Z_]*。只有內建標籤才允許以底線 _ 字元開頭。

如何使用自訂標籤取決於您。您可以在 Cluster 上設定自訂標籤以標記 Cluster 的位置。例如，在 Cluster 上設定一個名為 location 的自訂標籤，其值為 EMEA。