Перед использованием маркеров версии, установите их согласно инструкциям в разделе 5.5.5.2, «Установка или удаление маркеров версии».

Ситуация, в которой маркеры версии могут быть полезны, — это система, которая обращается к набору серверов MySQL, но нуждается в управлении ими для балансировки нагрузки, отслеживая их и корректируя назначения серверов в соответствии с изменениями нагрузки. Такая система состоит из следующих элементов:

Маркеры версии позволяют управлять доступом к серверу в соответствии с назначением, без необходимости, чтобы клиенты многократно запрашивали информацию о назначении серверов:

Логика клиентской стороны для обнаружения ошибок маркеров версии и выбора нового сервера может быть реализована различными способами:

Следующий пример иллюстрирует обсуждаемые моменты более конкретно.

Когда маркеры версии инициализируются на определённом сервере, список маркеров версии сервера пуст. Ведение списка маркеров выполняется путём вызова функций. Для вызова любой из функций маркеров версии требуется привилегия SUPER, поэтому ожидается, что изменение списка маркеров будет выполняться управляющим или административным приложением, имеющим это разрешение.

Предположим, что управляющее приложение взаимодействует с набором серверов, которые запрашиваются клиентами для доступа к базам данных сотрудников и продуктов (называемым emp и prod соответственно). Все серверы разрешено обрабатывать запросы на получение данных, но только некоторые из них разрешено выполнять обновления базы данных. Для обработки этого на базе данных, управляющее приложение устанавливает список маркеров версии на каждом сервере. В списке маркеров для данного сервера имена маркеров представляют имена баз данных, а значения маркеров — read или write в зависимости от того, должна ли база данных использоваться только для чтения или может принимать как чтения, так и записи.

Клиентские приложения регистрируют список маркеров версии, которые они требуют, чтобы сервер сопоставил, установив системную переменную. Установка переменной происходит на основе каждого клиента, поэтому разные клиенты могут регистрировать разные требования. По умолчанию список маркеров клиента пуст, что соответствует любому списку маркеров сервера. Когда клиент устанавливает свой список маркеров в ненулевое значение, соответствие может быть успешным или неудачным, в зависимости от списка маркеров версии сервера.

Чтобы определить список маркеров версии для сервера, управляющее приложение вызывает функцию version_tokens_set(). (Функции для изменения и отображения списка маркеров описаны ниже.) Например, приложение может отправить следующие инструкции группе из трёх серверов:

Сервер 1:

mysql> SELECT version_tokens_set('emp=read;prod=read');
+------------------------------------------+
| version_tokens_set('emp=read;prod=read') |
+------------------------------------------+
| 2 version tokens set.                    |
+------------------------------------------+

Сервер 2:

mysql> SELECT version_tokens_set('emp=write;prod=read');
+-------------------------------------------+
| version_tokens_set('emp=write;prod=read') |
+-------------------------------------------+
| 2 version tokens set.                     |
+-------------------------------------------+

Сервер 3:

mysql> SELECT version_tokens_set('emp=read;prod=write');
+-------------------------------------------+
| version_tokens_set('emp=read;prod=write') |
+-------------------------------------------+
| 2 version tokens set.                     |
+-------------------------------------------+

В каждом случае список маркеров указывается в виде списка пар name=value, разделённых точкой с запятой. Результирующие значения списков маркеров приводят к таким назначениям серверов:

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

Перед взаимодействием с серверами приложение-клиент связывается с управляющим приложением и извлекает информацию о назначениях серверов. Затем клиент выбирает сервер на основе этих назначений. Предположим, что клиент хочет выполнить как чтения, так и записи в базе данных emp. На основании предыдущих назначений подходит только сервер 2. Клиент подключается к серверу 2 и регистрирует свои требования к серверу, установив системную переменную version_tokens_session:

mysql> SET @@SESSION.version_tokens_session = 'emp=write';

Для последующих инструкций, отправленных клиентом на сервер 2, сервер сравнивает свой собственный список маркеров с клиентским списком, чтобы проверить, соответствуют ли они друг другу. Если да, инструкции выполняются нормально:

mysql> UPDATE emp.employee SET salary = salary * 1.1 WHERE id = 4981;
Query OK, 1 row affected (0.07 sec)
Rows matched: 1  Changed: 1  Warnings: 0

mysql> SELECT last_name, first_name FROM emp.employee WHERE id = 4981;
+-----------+------------+
| last_name | first_name |
+-----------+------------+
| Smith     | Abe        |
+-----------+------------+
1 row in set (0.01 sec)

Расхождения между списками маркеров версии сервера и клиента могут произойти двумя способами:

Пока назначение сервера 2 не изменится, клиент продолжает использовать его для чтения и записи. Но предположим, что управляющее приложение хочет изменить назначения серверов так, чтобы записи для базы данных emp должны быть отправлены на сервер 1 вместо сервера 2. Для этого оно использует version_tokens_edit() для изменения значения маркера emp на двух серверах (и обновляет свой кэш назначений серверов):

Сервер 1:

mysql> SELECT version_tokens_edit('emp=write');
+----------------------------------+
| version_tokens_edit('emp=write') |
+----------------------------------+
| 1 version tokens updated.        |
+----------------------------------+

Сервер 2:

mysql> SELECT version_tokens_edit('emp=read');
+---------------------------------+
| version_tokens_edit('emp=read') |
+---------------------------------+
| 1 version tokens updated.       |
+---------------------------------+

version_tokens_edit() изменяет указанные маркеры в списке маркеров сервера, оставляя другие маркеры неизменными.

В следующий раз, когда клиент отправит инструкцию на сервер 2, его собственный список маркеров больше не будет соответствовать списку маркеров сервера, и произойдёт ошибка:

mysql> UPDATE emp.employee SET salary = salary * 1.1 WHERE id = 4982;
ERROR 3136 (42000): Version token mismatch for emp. Correct value read

В этом случае клиент должен обратиться к управляющему приложению, чтобы получить обновлённую информацию о назначениях серверов, выбрать новый сервер и отправить необработанную инструкцию на новый сервер.

Для каждой инструкции, полученной от клиента, сервер неявно использует блокировку следующим образом:

Сервер использует общие блокировки, чтобы сравнения для нескольких сессий могли происходить без блокировки, одновременно предотвращая изменения маркеров для любой сессии, которая пытается получить эксклюзивную блокировку, прежде чем она манипулирует маркерами с одинаковыми именами в списке маркеров сервера.

В предыдущем примере использовались только некоторые из функций, включённых в библиотеку плагина маркеров версии, но есть и другие. Одна группа функций позволяет манипулировать и инспектировать список маркеров версии сервера. Другая группа функций позволяет блокировать и разблокировать маркеры версии.

Эти функции позволяют создавать, изменять, удалять и просматривать список маркеров версии сервера:

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

mysql> SELECT version_tokens_set('tok1=a;tok2=b');
+-------------------------------------+
| version_tokens_set('tok1=a;tok2=b') |
+-------------------------------------+
| 2 version tokens set.               |
+-------------------------------------+
mysql> SELECT version_tokens_edit('tok3=c');
+-------------------------------+
| version_tokens_edit('tok3=c') |
+-------------------------------+
| 1 version tokens updated.     |
+-------------------------------+
mysql> SELECT version_tokens_delete('tok2;tok1');
+------------------------------------+
| version_tokens_delete('tok2;tok1') |
+------------------------------------+
| 2 version tokens deleted.          |
+------------------------------------+
mysql> SELECT version_tokens_show();
+-----------------------+
| version_tokens_show() |
+-----------------------+
| tok3=c;               |
+-----------------------+

Возникают предупреждения, если список маркеров имеет неправильный формат:

mysql> SELECT version_tokens_set('tok1=a; =c');
+----------------------------------+
| version_tokens_set('tok1=a; =c') |
+----------------------------------+
| 1 version tokens set.            |
+----------------------------------+
1 row in set, 1 warning (0.00 sec)

mysql> SHOW WARNINGS\G
*************************** 1. row ***************************
  Level: Warning
   Code: 42000
Message: Invalid version token pair encountered. The list provided
         is only partially updated.
1 row in set (0.00 sec)

Как упоминалось ранее, маркеры версии определяются с помощью списка пар name=value, разделённых точкой с запятой. Рассмотрим такой вызов version_tokens_set():

mysql> SELECT version_tokens_set('tok1=b;;; tok2= a = b ; tok1 = 1\'2 3"4')
+---------------------------------------------------------------+
| version_tokens_set('tok1=b;;; tok2= a = b ; tok1 = 1\'2 3"4') |
+---------------------------------------------------------------+
| 3 version tokens set.                                         |
+---------------------------------------------------------------+

Маркеры версии интерпретируют аргумент следующим образом:

Учитывая эти правила, предыдущий вызов version_tokens_set() приводит к списку маркеров с двумя маркерами: tok1 имеет значение 1'2 3"4, а tok2 имеет значение a = b. Для проверки этого, вызовите version_tokens_show():

mysql> SELECT version_tokens_show();
+--------------------------+
| version_tokens_show()    |
+--------------------------+
| tok2=a = b;tok1=1'2 3"4; |
+--------------------------+

Если список маркеров содержит два маркера, почему version_tokens_set() вернул значение 3 version tokens set? Это произошло потому, что исходный список маркеров содержал два определения для tok1, и второе определение заменило первое.

Функции управления маркерами версии Version Tokens накладывают следующие ограничения на имена и значения маркеров:

Version Tokens также включает набор функций, позволяющих блокировать и разблокировать маркеры:

Каждая функция блокировки возвращает ненулевое значение при успешном выполнении. В противном случае происходит ошибка:

mysql> SELECT version_tokens_lock_shared('lock1', 'lock2', 0);
+-------------------------------------------------+
| version_tokens_lock_shared('lock1', 'lock2', 0) |
+-------------------------------------------------+
|                                               1 |
+-------------------------------------------------+

mysql> SELECT version_tokens_lock_shared(NULL, 0);
ERROR 3131 (42000): Incorrect locking service lock name '(null)'.

Блокировка с помощью функций блокировки Version Tokens является рекомендательной; приложения должны договариваться о сотрудничестве.

Возможна блокировка несуществующих имён маркеров. Это не создаёт маркеры.

Для функций блокировки Version Tokens имена маркеров в аргументах используются точно так, как указано. Окружающие пробелы не игнорируются, и = и ; символы допускаются. Это потому, что Version Tokens просто передаёт имена маркеров для блокировки как есть в службу блокировки.