#### 5.6.6.4 Version Tokens Reference

[]()

 The following discussion serves as a reference to these Version Tokens elements:

* [Version Tokens Functions](version-tokens-reference.html#version-tokens-routines)

* [Version Tokens System Variables](version-tokens-reference.html#version-tokens-system-variables)

##### Version Tokens Functions

 The Version Tokens plugin library includes several functions. One set of functions permits the server's list of version tokens to be manipulated and inspected. Another set of functions permits version tokens to be locked and unlocked. The [`VERSION_TOKEN_ADMIN`](privileges-provided.html#priv_version-token-admin) privilege (or the deprecated [`SUPER`](privileges-provided.html#priv_super) privilege) is required to invoke any Version Tokens function.

 The following functions permit the server's list of version tokens to be created, changed, removed, and inspected. Interpretation of *`name_list`* and *`token_list`* arguments (including whitespace handling) occurs as described in [Section 5.6.6.3, “Using Version Tokens”](version-tokens-usage.html), which provides details about the syntax for specifying tokens, as well as additional examples.

* []() [`version_tokens_delete(*`name_list`*)`](version-tokens-reference.html#function_version-tokens-delete)

  []()[]()

   Deletes tokens from the server's list of version tokens using the *`name_list`* argument and returns a binary string that indicates the outcome of the operation. *`name_list`* is a semicolon-separated list of version token names to delete.

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

   An argument of `NULL` is treated as an empty string, which has no effect on the token list.

  [`version_tokens_delete()`](version-tokens-reference.html#function_version-tokens-delete) deletes the tokens named in its argument, if they exist. (It is not an error to delete nonexisting tokens.) To clear the token list entirely without knowing which tokens are in the list, pass `NULL` or a string containing no tokens to [`version_tokens_set()`](version-tokens-reference.html#function_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`*)`](version-tokens-reference.html#function_version-tokens-edit)

  []()[]()

   Modifies the server's list of version tokens using the *`token_list`* argument and returns a binary string that indicates the outcome of the operation. *`token_list`* is a semicolon-separated list of `*`name`*=*`value`*` pairs specifying the name of each token to be defined and its value. If a token exists, its value is updated with the given value. If a token does not exist, it is created with the given value. If the argument is `NULL` or a string containing no tokens, the token list remains unchanged.

  ```
  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`*)`](version-tokens-reference.html#function_version-tokens-set)

  []()[]()

   Replaces the server's list of version tokens with the tokens defined in the *`token_list`* argument and returns a binary string that indicates the outcome of the operation. *`token_list`* is a semicolon-separated list of `*`name`*=*`value`*` pairs specifying the name of each token to be defined and its value. If the argument is `NULL` or a string containing no tokens, the token list is cleared.

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

* []() [`version_tokens_show()`](version-tokens-reference.html#function_version-tokens-show)

  []()[]()

   Returns the server's list of version tokens as a binary string containing a semicolon-separated list of `*`name`*=*`value`*` pairs.

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

 The following functions permit version tokens to be locked and unlocked:

* []() [`version_tokens_lock_exclusive(*`token_name`*[, *`token_name`*] ..., *`timeout`*)`](version-tokens-reference.html#function_version-tokens-lock-exclusive)

  []()[]()

   Acquires exclusive locks on one or more version tokens, specified by name as strings, timing out with an error if the locks are not acquired within the given timeout value.

  ```
  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`*)`](version-tokens-reference.html#function_version-tokens-lock-shared)

  []()[]()

   Acquires shared locks on one or more version tokens, specified by name as strings, timing out with an error if the locks are not acquired within the given timeout value.

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

* []() [`version_tokens_unlock()`](version-tokens-reference.html#function_version-tokens-unlock)

  []()[]()

   Releases all locks that were acquired within the current session using [`version_tokens_lock_exclusive()`](version-tokens-reference.html#function_version-tokens-lock-exclusive) and [`version_tokens_lock_shared()`](version-tokens-reference.html#function_version-tokens-lock-shared).

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

 The locking functions share these characteristics:

* The return value is nonzero for success. Otherwise, an error occurs.

* Token names are strings.

* In contrast to argument handling for the functions that manipulate the server token list, whitespace surrounding token name arguments is not ignored and `=` and `;` characters are permitted.

* It is possible to lock nonexisting token names. This does not create the tokens.

* Timeout values are nonnegative integers representing the time in seconds to wait to acquire locks before timing out with an error. If the timeout is 0, there is no waiting and the function produces an error if locks cannot be acquired immediately.

* Version Tokens locking functions are based on the locking service described at [Section 5.6.9.1, “The Locking Service”](locking-service.html).

##### Version Tokens System Variables

 Version Tokens supports the following system variables. These variables are unavailable unless the Version Tokens plugin is installed (see [Section 5.6.6.2, “Installing or Uninstalling Version Tokens”](version-tokens-installation.html)).

 System variables:

* []() [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session)

  []()[]()

  |                         Command-Line Format                          |                           `--version-tokens-session=value`                            |
  |----------------------------------------------------------------------|---------------------------------------------------------------------------------------|
  |                           System Variable                            |`[version_tokens_session](version-tokens-reference.html#sysvar_version_tokens_session)`|
  |                                Scope                                 |                                    Global, Session                                    |
  |                               Dynamic                                |                                          Yes                                          |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                          No                                           |
  |                                 Type                                 |                                        String                                         |
  |                            Default Value                             |                                        `NULL`                                         |

   The session value of this variable specifies the client version token list and indicates the tokens that the client session requires the server version token list to have.

   If the [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session) variable is `NULL` (the default) or has an empty value, any server version token list matches. (In effect, an empty value disables matching requirements.)

   If the [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session) variable has a nonempty value, any mismatch between its value and the server version token list results in an error for any statement the session sends to the server. A mismatch occurs under these conditions:

  * A token name in the [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session) value is not present in the server token list. In this case, an [`ER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_vtoken_plugin_token_not_found) error occurs.

  * A token value in the [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session) value differs from the value of the corresponding token in the server token list. In this case, an [`ER_VTOKEN_PLUGIN_TOKEN_MISMATCH`](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html#error_er_vtoken_plugin_token_mismatch) error occurs.

   It is not a mismatch for the server version token list to include a token not named in the [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session) value.

   Suppose that a management application has set the server token list as follows:

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

   A client registers the tokens it requires the server to match by setting its [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session) value. Then, for each subsequent statement sent by the client, the server checks its token list against the client [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session) value and produces an error if there is a mismatch:

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

   The first [`SELECT`](select.html) succeeds because the client tokens `tok1` and `tok2` are present in the server token list and each token has the same value in the server list. The second [`SELECT`](select.html) fails because, although `tok1` is present in the server token list, it has a different value than specified by the client.

   At this point, any statement sent by the client fails, unless the server token list changes such that it matches again. Suppose that the management application changes the server token list as follows:

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

   Now the client [`version_tokens_session`](version-tokens-reference.html#sysvar_version_tokens_session) value matches the server token list and the client can once again successfully execute statements:

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

* []() [`version_tokens_session_number`](version-tokens-reference.html#sysvar_version_tokens_session_number)

  []()[]()

  |                         Command-Line Format                          |                                 `--version-tokens-session-number=#`                                 |
  |----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
  |                           System Variable                            |`[version_tokens_session_number](version-tokens-reference.html#sysvar_version_tokens_session_number)`|
  |                                Scope                                 |                                           Global, Session                                           |
  |                               Dynamic                                |                                                 No                                                  |
  |[`SET_VAR`](optimizer-hints.html#optimizer-hints-set-var) Hint Applies|                                                 No                                                  |
  |                                 Type                                 |                                               Integer                                               |
  |                            Default Value                             |                                                 `0`                                                 |

   This variable is for internal use.

