バージョントークンを使用する前に、セクション5.6.6.2「バージョントークンのインストールまたはアンインストール」 に記載されている手順に従ってインストールします。

バージョントークンが役立つシナリオは、MySQL サーバーのコレクションにアクセスするシステムですが、ロードバランシングの目的でそれらを監視し、負荷の変更に応じてサーバー割当てを調整することで管理する必要があります。 このようなシステムは、次の要素で構成されます:

バージョントークンを使用すると、クライアントが割当てについてサーバーに繰り返しクエリーすることなく、割当てに従ってサーバーアクセスを管理できます:

バージョントークンエラーを検出して新しいサーバーを選択するためのクライアント側ロジックは、様々な方法で実装できます:

次の例は、より具体的な形式で前述の説明を示しています。

特定のサーバーでバージョントークンが初期化されると、サーバーバージョントークンリストは空になります。 トークンリストのメンテナンスは、ユーザー定義関数 (UDF) をコールすることで実行されます。 任意のバージョントークン UDF をコールするには、VERSION_TOKEN_ADMIN 権限 (または非推奨の SUPER 権限) が必要であるため、トークンリストの変更は、その権限を持つ管理アプリケーションまたは管理アプリケーションによって実行される必要があります。

管理アプリケーションが、従業員および製品データベース (それぞれ emp および prod という名前) にアクセスするためにクライアントによってクエリーされる一連のサーバーと通信するとします。 すべてのサーバーでデータ取得ステートメントの処理が許可されていますが、一部のサーバーでのみデータベースの更新が許可されています。 これをデータベース固有のベースで処理するために、管理アプリケーションは各サーバーにバージョントークンのリストを確立します。 特定のサーバーのトークンリストでは、トークン名はデータベース名を表し、トークン値は、データベースを読取り専用で使用する必要があるかどうか、または読取りおよび書込みが可能かどうかに応じて read または write です。

クライアントアプリケーションは、システム変数を設定して、サーバーが一致する必要があるバージョントークンのリストを登録します。 変数の設定はクライアント固有のベースで行われるため、クライアントごとに異なる要件を登録できます。 デフォルトでは、クライアントトークンリストは空で、任意のサーバートークンリストに一致します。 クライアントがトークンリストを空でない値に設定すると、サーバーバージョンのトークンリストに応じて、照合が成功または失敗する場合があります。

サーバーのバージョントークンリストを定義するために、管理アプリケーションは version_tokens_set() UDF を呼び出します。 (後で説明するように、トークンリストを変更および表示するための UDF もあります。) たとえば、アプリケーションは次のステートメントを 3 つのサーバーのグループに送信します:

サーバー 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 つの方法で発生します:

サーバー 2 の割り当てが変更されないかぎり、クライアントはそれを読み取りおよび書き込みに引き続き使用します。 ただし、管理アプリケーションがサーバー割当てを変更して、emp データベースの書込みをサーバー 2 ではなくサーバー 1 に送信する必要があるとします。 これを行うには、version_tokens_edit() を使用して、2 つのサーバーの 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

この場合、クライアントは管理アプリケーションに連絡して、サーバー割当てに関する更新情報を取得し、新しいサーバーを選択して、失敗したステートメントを新しいサーバーに送信する必要があります。

クライアントから受信したステートメントごとに、サーバーは次のように暗黙的にロックを使用します:

サーバーは共有ロックを使用するため、ブロックせずに複数のセッションの比較を行うことができますが、サーバートークンリスト内の同じ名前のトークンを操作する前に排他ロックを取得しようとするセッションのトークンに対する変更を防止します。

前述の例では、バージョントークンプラグインライブラリに含まれているユーザー定義の一部のみを使用していますが、他にもあります。 UDF のセットでは、バージョントークンのサーバーリストを操作および検査できます。 UDF の別のセットでは、バージョントークンをロックおよびロック解除できます。

次の UDF を使用すると、バージョントークンのサーバーリストを作成、変更、削除および検査できます:

これらの各関数は、成功した場合、発生したアクションを示すバイナリ文字列を返します。 次の例では、サーバートークンリストを確立し、新しいトークンを追加して変更し、一部のトークンを削除して、結果のトークンリストを表示します:

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() コールの結果、2 つのトークンを含むトークンリストが生成されます: 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; |
+--------------------------+

トークンリストに 2 つのトークンが含まれている場合、version_tokens_set() が値 3 version tokens set を返したのはなぜですか。 これは、元のトークンリストに tok1 の 2 つの定義が含まれ、2 つ目の定義が最初の定義に置き換わったために発生しました。

バージョントークンのトークン操作 UDF は、トークン名と値に次の制約を設定します:

バージョントークンには、トークンをロックおよびロック解除できる UDF のセットも含まれています:

各ロック関数は、成功した場合はゼロ以外を返します。 それ以外の場合は、次のエラーが発生します:

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)'.

バージョントークンロック機能を使用したロックは勧告です。アプリケーションは協調する必要があります。

存在しないトークン名をロックできます。 トークンは作成されません。

バージョントークンロック関数の場合、トークン名引数は指定したとおりに正確に使用されます。 前後の空白は無視されず、= および;文字は許可されます。 これは、バージョントークンが単にロック対象のトークン名をロックサービスにそのまま渡すためです。