7.8.1 Routing Guidelines JSON Syntax — MySQL Shell 9.2

7.8.1 Синтаксис руководства по маршрутизации JSON

Основные свойства документа по маршрутизации:

destinations: группировки серверов MySQL с использованием выражений сопоставления шаблонов. Выражения определяют, какие серверы включены в пункт назначения. Каждый пункт назначения — это пул кандидатов для маршрутизации. Серверы могут принадлежать нескольким пунктам назначения одновременно. При формировании пула кандидатов учитываются только члены топологии, находящиеся в онлайн-режиме.
name: имя руководства по маршрутизации.
routes: выражения, сопоставляющие входящие сеансы клиентов с соответствующими кандидатами в пунктах назначения.
version: версия документа Руководства по маршрутизации.

{
  "destinations": [destinationDefinitions],
  "name": [Name of the routing guidelines document],
  "routes": [routeDefinitions],
  "version": [Version of the routing guidelines document]
}

Имя и версия

name: имя документа Руководства по маршрутизации.
version: версия документа руководства по маршрутизации. Все новые Руководства по маршрутизации создаются с версией 1.0.

Пункты назначения

Классы пунктов назначения позволяют группировать экземпляры MySQL по определенным критериям.

Следующий пример демонстрирует стандартный класс пункта назначения для InnoDB Cluster:

  "destinations": [
      {
          "match": "$.server.memberRole = PRIMARY",
          "name": "Primary"
      },
      {
          "match": "$.server.memberRole = SECONDARY",
          "name": "Secondary"
      },
      {
          "match": "$.server.memberRole = READ_REPLICA",
          "name": "ReadReplica"
      }
  ],

Каждое из выражений сопоставления оценивается как адреса членов кластера. Определенные в классах маршрутов выражения определяют, как входящие соединения направляются на эти адреса.

Маршруты

Каждый класс маршрутов содержит следующее:

connectionSharingAllowed: (boolean) Указывает, разрешает ли маршрут совместное использование подключений. Это соответствует параметру конфигурации MySQL Router, connection_sharing. Для получения дополнительной информации см. connection_sharing.
destinations: группы пунктов назначения, упорядоченные по приоритету.
- classes: определяют отдельные группы пунктов назначения, используя имена, определенные в классе пунктов назначения.
- priority: приоритет группы маршрутизации.
- strategy: соответствует параметру MySQL Router routing_strategy, либо first-available, либо round-robin.
  
  Для получения дополнительной информации см. routing_strategy.
- match: выражение сопоставления для входящих сеансов клиентов.
- name: имя маршрута.

Следующий пример демонстрирует стандартный класс маршрутов для кластера InnoDB из трех членов:

   "routes": [
    {
        "connectionSharingAllowed": true,
        "destinations": [
            {
                "classes": [
                    "Primary"
                ],
                "priority": 0,
                "strategy": "round-robin"
            }
        ],
        "enabled": true,
        "match": "$.session.targetPort = $.router.port.rw",
        "name": "rw"
    },
    {
        "connectionSharingAllowed": true,
        "destinations": [
            {
                "classes": [
                    "Secondary"
                ],
                "priority": 0,
                "strategy": "round-robin"
            },
            {
                "classes": [
                    "Primary"
                ],
                "priority": 1,
                "strategy": "round-robin"
            }
        ],
        "enabled": true,
        "match": "$.session.targetPort = $.router.port.ro",
        "name": "ro"
    }
],

Эти два маршрута направляют трафик чтение-запись только на первичный, в то время как трафик только для чтения сначала направляется во вторичный пункт назначения, а затем — в первичный, если вторичный не доступен. Для обоих используется стратегия маршрутизации циклического перебора, а также совместное использование подключений.

Правила сопоставления

Правила сопоставления для маршрутизации используют следующие переменные, операторы и функции.

Переменные:

$.router.bindAddress: (строка) соответствует IP-адресу, на котором маршрутизатор настроен для прослушивания входящих соединений. Адрес должен быть корректной строкой IPv4 или IPv6.
$.router.hostname: (строка) соответствует имени хоста машины, на которой запущен MySQL Router.
$.router.localCluster: (строка) соответствует имени кластера, к которому был произведен запуск MySQL Router, или имени кластера, заданного в --conf-target-cluster.
$.router.port.ro: (целое число) соответствует номеру порта, на котором MySQL Router прослушивает входящие соединения для чтения. Должно быть положительным целым числом в диапазоне от 1 до 65535 включительно.
$.router.port.rw: (целое число) соответствует номеру порта, на котором MySQL Router прослушивает входящие соединения для чтения и записи.
$.router.port.rw_split: (целое число) соответствует номеру порта, на котором MySQL Router прослушивает входящие соединения для разделения чтения и записи.
$.router.routeName: соответствует имени плагина маршрутизации, используемого маршрутизатором.
$.router.tags.tagName: (строка) соответствует определённому пользователем значению tagName, определённому в метаданных для этого маршрутизатора.
$.server.address: (строка) соответствует IP-адресу сервера. Адрес должен быть корректной строкой IPv4 или IPv6.
$.server.clusterName: (строка) соответствует имени кластера InnoDB, к которому принадлежит сервер.
$.server.clusterRole: (перечисление) соответствует роли кластера в InnoDB ClusterSet. Допустимые значения: PRIMARY, SECONDARY и READ_REPLICA.
$.server.clusterSetName: (строка) соответствует имени InnoDB ClusterSet, к которому принадлежит сервер.
$.server.isClusterInvalidated: (логическое) соответствует серверам, которые являются членами кластера InnoDB, аннулированного во время переключения.
$.server.label: (строка) соответствует метке сервера, определенной в метаданных.
$.server.memberRole: (перечисление) соответствует роли члена кластера InnoDB. Допустимые значения: PRIMARY, SECONDARY и READ_REPLICA.
$.server.port: (целое число) соответствует открытому порту, используемому сервером для входящих соединений. Должно быть положительным целым числом в диапазоне от 1 до 65535 включительно.
$.server.tag.tagName: (строка) соответствует определённому пользователем значению tagName, определённому в метаданных для этого сервера.
$.server.uuid: (строка) соответствует значению server_uuid, определённому в метаданных.
$.server.version: (целое число) соответствует определённой версии сервера. Формат должен быть XXYYZZ, где X - основная версия, YY - второстепенная версия, а ZZ - версия патча. Например, 8.0.39 - это 80039, 8.4.3 - 80403, а 9.2.0 - 90200.
Примечание

Следующие варианты не поддерживаются:
- Реплики чтения
- Члены InnoDB ReplicaSet
- Версии MySQL 8.0.2 и ниже.
$.session.connectAttrs.connectAttributes: (строка) соответствует атрибутам подключения сессии.
$.session.randomValue: (двойное) соответствует случайному значению в диапазоне 0.0 ≤ x < 1.0.
$.session.schema: (строка) соответствует схеме по умолчанию, указанной при подключении.
$.session.sourceIP: (строка) соответствует IP-адресу, с которого происходит подключение сессии. Адрес должен быть корректной строкой IPv4 или IPv6.
$.session.targetIP: (строка) соответствует IP-адресу маршрутизатора, к которому подключилась сессия. Адрес должен быть корректной строкой IPv4 или IPv6.
$.session.targetPort: (целое число) соответствует порту маршрутизатора, к которому подключена сессия. Должно быть положительным целым числом в диапазоне от 1 до 65535 включительно.
$.session.user: (строка) соответствует аутентифицированному пользователю сессии.

Функции и операторы:

Группировка выражений с помощью скобок ().
Логические операторы: AND, OR и NOT.
Проверки включения: IN и NOT IN.
Арифметические операции: сложение (+), вычитание (-), умножение (*), деление (/), и деление по модулю (%).
Сравнения: больше чем (>), больше или равно (>=), меньше чем (<), меньше или равно (<=), равно (=), не равно (<>).
LIKE: позволяет сопоставление с образцом. Подчеркивание (_) соответствует любому символу, а процент (%) соответствует любому символу с любым числом повторений.
CONCAT('str', 'str', ...): позволяет конкатенацию нескольких строк, возвращая строку в качестве результата. Например: CONCAT('a', 'b', 'cde') возвращает abcde.
SQRT('number'): вычисляет квадратный корень из заданного числа, возвращая дробное значение в качестве результата. Например: SQRT(0.16) возвращает 0.4.
NUMBER('str'): преобразует строку в число. Например: NUMBER(CONCAT('1', '2')) = 12
NETWORK('str', 'int'): вычисляет сетевой адрес для заданного адреса и маски. Возвращает сетевой адрес в виде строки. Например: NETWORK('192.168.1.33', 24) возвращает диапазон от 192.168.1.0 до 192.168.1.255.
IS_IPV6('str'): проверяет, является ли заданная строка корректным IP-адресом IPv4. Возвращает логическое значение, true/false.
IS_IPV6('str'): проверяет, является ли заданная строка корректным IP-адресом IPv6. Возвращает логическое значение, true/false.
STARTSWITH('str1', 'str2'): проверяет, является ли строка str2 префиксом строки str1. Без учета регистра. Возвращает логическое значение, true/false.
ENDSWITH('str1', 'str2'): проверяет, является ли строка str2 суффиксом строки str1. Без учета регистра. Возвращает логическое значение, true/false.
CONTAINS('str1', 'str2'): проверяет, является ли строка str2 подстрокой строки str1, без учета регистра. Возвращает логическое значение, true/false.
RESOLVE_V4('str'): разрешает имена хостов, переданные в виде строкового параметра, в IP-адрес IPv4. Возвращает строку, содержащую разрешенный адрес. Если имя хоста может быть разрешено к нескольким адресам, возвращается только один из адресов.
RESOLVE_V6('str'): разрешает имена хостов, переданные в виде строкового параметра, в IP-адрес IPv6. Возвращает строку, содержащую разрешенный адрес. Если имя хоста может быть разрешено к нескольким адресам, возвращается только один из адресов.
REGEXP_LIKE('str1', 'str2'): проверяет, соответствует ли str1 заданному в str2 регулярному выражению. Без учета регистра и использует грамматику регулярных выражений Modified ECMAScript.