このページは機械翻訳したものです。

5.6.6.4 バージョントークン参照

次の説明は、これらのバージョントークン要素への参照として機能します:

• バージョントークン関数

• バージョントークンシステム変数

バージョントークン関数

バージョントークンプラグインライブラリには、複数のユーザー定義関数が含まれています。 UDF のセットでは、バージョントークンのサーバーリストを操作および検査できます。 UDF の別のセットでは、バージョントークンをロックおよびロック解除できます。 バージョントークン UDF を起動するには、VERSION_TOKEN_ADMIN 権限 (または非推奨の SUPER 権限) が必要です。

次の UDF を使用すると、バージョントークンのサーバーリストを作成、変更、削除および検査できます。 name_list および token_list の引数 (空白の処理を含む) の解釈は、セクション5.6.6.3「バージョントークンの使用」 で説明されているように行われます。ここでは、トークンを指定するための構文とその他の例について詳しく説明します。

• version_tokens_delete(name_list)

  name_list 引数を使用してバージョントークンのサーバーリストからトークンを削除し、操作の結果を示すバイナリ文字列を返します。name_list は、削除するバージョントークン名のセミコロン区切りリストです。

  mysql> SELECT version_tokens_delete('tok1;tok3');
  +------------------------------------+
  | version_tokens_delete('tok1;tok3') |
  +------------------------------------+
  | 2 version tokens deleted.          |
  +------------------------------------+

  NULL の引数は空の文字列として扱われ、トークンリストには影響しません。

  version_tokens_delete() は、引数に指定されたトークンが存在する場合、それらを削除します。 (存在しないトークンを削除してもエラーになりません。) リストに含まれるトークンを知らずにトークンリストを完全にクリアするには、NULL またはトークンを含まない文字列を version_tokens_set() に渡します:

  mysql> SELECT version_tokens_set(NULL);
  +------------------------------+
  | version_tokens_set(NULL)     |
  +------------------------------+
  | Version tokens list cleared. |
  +------------------------------+
  mysql> SELECT version_tokens_set('');
  +------------------------------+
  | version_tokens_set('')       |
  +------------------------------+
  | Version tokens list cleared. |
  +------------------------------+

• version_tokens_edit(token_list)

  token_list 引数を使用してバージョントークンのサーバーリストを変更し、操作の結果を示すバイナリ文字列を返します。token_list は、定義する各トークンの名前とその値を指定する name=value ペアのセミコロン区切りリストです。 トークンが存在する場合、その値は指定された値で更新されます。 トークンが存在しない場合は、指定された値で作成されます。 引数が NULL であるか、トークンを含まない文字列である場合、トークンリストは変更されません。

  mysql> SELECT version_tokens_set('tok1=value1;tok2=value2');
  +-----------------------------------------------+
  | version_tokens_set('tok1=value1;tok2=value2') |
  +-----------------------------------------------+
  | 2 version tokens set.                         |
  +-----------------------------------------------+
  mysql> SELECT version_tokens_edit('tok2=new_value2;tok3=new_value3');
  +--------------------------------------------------------+
  | version_tokens_edit('tok2=new_value2;tok3=new_value3') |
  +--------------------------------------------------------+
  | 2 version tokens updated.                              |
  +--------------------------------------------------------+

• version_tokens_set(token_list)

  バージョントークンのサーバーリストを token_list 引数で定義されたトークンに置き換え、操作の結果を示すバイナリ文字列を返します。token_list は、定義する各トークンの名前とその値を指定する name=value ペアのセミコロン区切りリストです。 引数が NULL であるか、トークンを含まない文字列である場合、トークンリストはクリアされます。

  mysql> SELECT version_tokens_set('tok1=value1;tok2=value2');
  +-----------------------------------------------+
  | version_tokens_set('tok1=value1;tok2=value2') |
  +-----------------------------------------------+
  | 2 version tokens set.                         |
  +-----------------------------------------------+

• version_tokens_show()

  バージョントークンのサーバーリストを、name=value ペアのセミコロン区切りリストを含むバイナリ文字列として返します。

  mysql> SELECT version_tokens_show();
  +--------------------------+
  | version_tokens_show()    |
  +--------------------------+
  | tok2=value2;tok1=value1; |
  +--------------------------+

次の UDF を使用すると、バージョントークンをロックおよびロック解除できます:

• version_tokens_lock_exclusive(token_name[, token_name] ..., timeout)

  指定されたタイムアウト値内にロックが取得されない場合、名前で文字列として指定された 1 つ以上のバージョントークンの排他ロックを取得し、エラーでタイムアウトします。

  mysql> SELECT version_tokens_lock_exclusive('lock1', 'lock2', 10);
  +-----------------------------------------------------+
  | version_tokens_lock_exclusive('lock1', 'lock2', 10) |
  +-----------------------------------------------------+
  |                                                   1 |
  +-----------------------------------------------------+

• version_tokens_lock_shared(token_name[, token_name] ..., timeout)

  指定されたタイムアウト値内にロックが取得されない場合、名前で文字列として指定された 1 つ以上のバージョントークンの共有ロックを取得し、エラーでタイムアウトします。

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

• version_tokens_unlock()

  version_tokens_lock_exclusive() および version_tokens_lock_shared() を使用して、現在のセッション内で取得されたすべてのロックを解放します。

  mysql> SELECT version_tokens_unlock();
  +-------------------------+
  | version_tokens_unlock() |
  +-------------------------+
  |                       1 |
  +-------------------------+

ロック関数は、次の特性を共有します:

• 成功の場合、戻り値はゼロ以外です。 それ以外の場合は、エラーが発生します。

• トークン名は文字列です。

• サーバートークンリストを操作する UDF の引数処理とは対照的に、トークン名引数を囲む空白は無視されず、= および;文字は許可されます。

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

• タイムアウト値は、エラーでタイムアウトするまでにロックの取得を待機する時間 (秒) を表す負でない整数です。 タイムアウトが 0 の場合、待機はなく、ロックをすぐに取得できないと、関数はエラーを生成します。

• バージョントークンのロック関数は、セクション5.6.8.1「ロックサービス」 で説明されているロックサービスに基づいています。

バージョントークンシステム変数

バージョントークンでは、次のシステム変数がサポートされます。 これらの変数は、バージョントークンプラグインがインストールされていないかぎり使用できません (セクション5.6.6.2「バージョントークンのインストールまたはアンインストール」 を参照)。

システム変数:

• version_tokens_session

  コマンド行形式	--version-tokens-session=value
  システム変数	version_tokens_session
  スコープ	グローバル、セッション
  動的	はい
  SET_VAR ヒントの適用	いいえ
  型	文字列
  デフォルト値	NULL

  この変数のセッション値は、クライアントバージョントークンリストを指定し、クライアントセッションがサーバーバージョンのトークンリストを持つ必要があるトークンを示します。

  version_tokens_session 変数が NULL (デフォルト) であるか、値が空の場合、サーバーバージョンのトークンリストが一致します。 (実際には、空の値を指定すると、一致する要件が無効になります。)

  version_tokens_session 変数に空でない値が含まれている場合、その値とサーバーバージョンのトークンリストが一致しないと、セッションがサーバーに送信するステートメントでエラーが発生します。 次の条件下で不一致が発生します:

  • version_tokens_session 値のトークン名がサーバートークンリストに存在しません。 この場合、ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND エラーが発生します。

  • version_tokens_session 値のトークン値は、サーバートークンリストの対応するトークンの値とは異なります。 この場合、ER_VTOKEN_PLUGIN_TOKEN_MISMATCH エラーが発生します。

  サーバーバージョンのトークンリストに version_tokens_session 値に指定されていないトークンが含まれていても、不一致ではありません。

  管理アプリケーションでサーバートークンリストが次のように設定されているとします:

  mysql> SELECT version_tokens_set('tok1=a;tok2=b;tok3=c');
  +--------------------------------------------+
  | version_tokens_set('tok1=a;tok2=b;tok3=c') |
  +--------------------------------------------+
  | 3 version tokens set.                      |
  +--------------------------------------------+

  クライアントは、version_tokens_session 値を設定して、サーバーが一致する必要があるトークンを登録します。 次に、クライアントによって送信される後続のステートメントごとに、サーバーはそのトークンリストをクライアントの version_tokens_session 値と照合してチェックし、不一致がある場合はエラーを生成します:

  mysql> SET @@SESSION.version_tokens_session = 'tok1=a;tok2=b';
  mysql> SELECT 1;
  +---+
  | 1 |
  +---+
  | 1 |
  +---+
  
  mysql> SET @@SESSION.version_tokens_session = 'tok1=b';
  mysql> SELECT 1;
  ERROR 3136 (42000): Version token mismatch for tok1. Correct value a

  クライアントトークン tok1 および tok2 がサーバートークンリストに存在し、各トークンの値がサーバーリストに同じであるため、最初の SELECT は成功します。 tok1 はサーバートークンリストに存在しますが、クライアントで指定された値とは異なるため、2 番目の SELECT は失敗します。

  この時点で、サーバートークンリストが再度一致するように変更されないかぎり、クライアントによって送信されたステートメントは失敗します。 管理アプリケーションがサーバートークンリストを次のように変更するとします:

  mysql> SELECT version_tokens_edit('tok1=b');
  +-------------------------------+
  | version_tokens_edit('tok1=b') |
  +-------------------------------+
  | 1 version tokens updated.     |
  +-------------------------------+
  mysql> SELECT version_tokens_show();
  +-----------------------+
  | version_tokens_show() |
  +-----------------------+
  | tok3=c;tok1=b;tok2=b; |
  +-----------------------+

  これで、クライアントの version_tokens_session 値がサーバートークンリストと一致し、クライアントがステートメントを再度正常に実行できるようになります:

  mysql> SELECT 1;
  +---+
  | 1 |
  +---+
  | 1 |
  +---+

• version_tokens_session_number

  コマンド行形式	--version-tokens-session-number=#
  システム変数	version_tokens_session_number
  スコープ	グローバル、セッション
  動的	いいえ
  SET_VAR ヒントの適用	いいえ
  型	Integer
  デフォルト値	0

  この変数は内部で使用されます。