5.5.5.4 版本令牌参考

以下讨论可作为对这些版本令牌组件的参考：

版本令牌功能

版本令牌插件库包括几个用户定义的函数。一组 UDF 允许操作和检查服务器的版本令牌列 table。另一组 UDF 允许锁定和解锁版本令牌。调用任何版本令牌 UDF 都需要SUPER特权。

以下 UDF 允许创建，更改，删除和检查服务器的版本令牌列 table。如第 5.5.5.3 节“使用版本令牌”所述，对* name_list 和 token_list *参数(包括空格处理)进行解释，其中提供了有关指定标记的语法的详细信息以及其他示例。

version_tokens_delete(name_list)

使用* name_list *参数从服务器的版本令牌列 table 中删除令牌，并返回指示操作结果的二进制字符串。 * name_list *是要删除的版本令牌名称的列 table，以分号分隔。

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

NULL的参数被视为空字符串，这对令牌列 table 没有影响。

version_tokens_delete()删除其参数中命名的标记(如果存在)。 (删除不存在的令牌不是错误.)要完全清除令牌列 table 而又不知道列 table 中有哪些令牌，请将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 *参数修改服务器的版本令牌列 table，并返回指示操作结果的二进制字符串。 * token_list *是name=value对的分号分隔列 table，用于指定要定义的每个标记的名称及其值。如果令牌存在，则将其值更新为给定值。如果令牌不存在，则会使用给定值创建令牌。如果参数是NULL或不包含令牌的字符串，则令牌列 table 保持不变。

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 *参数中定义的标记替换服务器的版本标记列 table，并返回指示操作结果的二进制字符串。 * token_list *是name=value对的分号分隔列 table，用于指定要定义的每个标记的名称及其值。如果参数是NULL或不包含令牌的字符串，则清除令牌列 table。

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

version_tokens_show()

以二进制字符串形式返回服务器的版本令牌列 table，该二进制字符串包含以分号分隔的name=value对列 table。

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

以下 UDF 允许版本令牌被锁定和解锁：

version_tokens_lock_exclusive(令牌名[，令牌名] ...，超时)

获取一个或多个版本令牌的排他锁，这些令牌由名称指定为字符串，如果未在给定的超时值内获取锁，则会超时并显示错误。

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

version_tokens_lock_shared(令牌名[，令牌名] ...，超时)

获取一个或多个版本令牌的共享锁，这些共享令牌由名称指定为字符串，如果未在给定的超时值内获取锁，则会超时并显示错误。

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 |
+-------------------------+

锁定功能具有以下 Feature：

成功返回值非零。否则，将发生错误。
令牌名称是字符串。
与操作服务器令牌列 table 的 UDF 的参数处理相比，令牌名称参数周围的空格不会被忽略，并且允许=和;个字符。
可以锁定不存在的令牌名称。这不会创建令牌。
超时值是非负整数，table 示错误超时之前 await 获取锁的时间(以秒为单位)。如果超时为 0，则没有 await，如果无法立即获取锁，该函数将产生错误。
版本令牌锁定功能基于第 28.3.1 节“锁定服务”中描述的锁定服务。

版本令牌系统变量

版本令牌支持以下系统变量。除非安装了 Version Tokens 插件，否则这些变量不可用(请参阅第 5.5.5.2 节“安装或卸载版本令牌”)。

System variables:

version_tokens_session

Property	Value
Command-Line Format	`--version-tokens-session=value`
System Variable	`version_tokens_session`
Scope	Global, Session
Dynamic	Yes
Type	String
Default Value	`NULL`

此变量的会话值指定 Client 端版本令牌列 table，并指示 Client 端会话要求服务器版本令牌列 table 具有的令牌。

如果version_tokens_session变量为NULL(默认值)或值为空，则任何服务器版本令牌列 table 都匹配。 (实际上，空值将禁用匹配要求.)

如果version_tokens_session变量具有非空值，则其值与服务器版本令牌列 table 之间的任何不匹配都会导致会话发送到服务器的任何语句出错。在以下情况下会发生不匹配：

服务器令牌列 table 中没有version_tokens_session值中的令牌名称。在这种情况下，发生ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND错误。
- version_tokens_session值中的令牌值与服务器令牌列 table 中相应令牌的值不同。在这种情况下，发生ER_VTOKEN_PLUGIN_TOKEN_MISMATCH错误。

服务器版本令牌列 table 包括未在version_tokens_session值中命名的令牌，这并非不匹配。

假设 Management 应用程序已如下设置服务器令牌列 table：

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

Client 端通过设置其version_tokens_session值来注册它要求服务器匹配的令牌。然后，对于 Client 端发送的每个后续语句，服务器将根据 Client 端version_tokens_session值检查其令牌列 table，如果不匹配，则会产生错误：

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

第一个SELECT成功，因为服务器令牌列 table 中存在 Client 端令牌tok1和tok2，并且每个令牌在服务器列 table 中具有相同的值。第二个SELECT失败是因为尽管tok1存在于服务器令牌列 table 中，但它的值与 Client 端指定的值不同。

此时，除非服务器令牌列 table 更改为再次匹配，否则 Client 端发送的任何语句都会失败。假设 Management 应用程序更改服务器令牌列 table，如下所示：

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; |
+-----------------------+

现在，Client 端version_tokens_session的值与服务器令牌列 table 匹配，并且 Client 端可以再次成功执行语句：

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

version_tokens_session_number

Property	Value
Command-Line Format	`--version-tokens-session-number=#`
System Variable	`version_tokens_session_number`
Scope	Global, Session
Dynamic	No
Type	Integer
Default Value	`0`

此变量仅供内部使用。

Name	MySql 中文文档
Version
Language
Badge
Last Updated	2021-07-03T12:24:35