Rechercher dans le manuel MySQL
5.6.6.4 Version Tokens Reference
The following discussion serves as a reference to these Version Tokens components:
Version Tokens Functions
The Version Tokens plugin library includes several
user-defined functions. One set of UDFs permits the server's
list of version tokens to be manipulated and inspected.
Another set of UDFs permits version tokens to be locked and
unlocked. The
VERSION_TOKEN_ADMIN
or
SUPER
privilege is required to
invoke any Version Tokens UDF.
The following UDFs 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”, which provides details
about the syntax for specifying tokens, as well as additional
examples.
version_tokens_delete(
name_list
)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.- +------------------------------------+
- | version_tokens_delete('tok1;tok3') |
- +------------------------------------+
- +------------------------------------+
An argument of
NULL
is treated as an empty string, which has no effect on the token list.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, passNULL
or a string containing no tokens toversion_tokens_set()
:- +------------------------------+
- +------------------------------+
- +------------------------------+
- +------------------------------+
- | version_tokens_set('') |
- +------------------------------+
- +------------------------------+
version_tokens_edit(
token_list
)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
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 isname
=value
NULL
or a string containing no tokens, the token list remains unchanged.- +-----------------------------------------------+
- | version_tokens_set('tok1=value1;tok2=value2') |
- +-----------------------------------------------+
- +-----------------------------------------------+
- +--------------------------------------------------------+
- | version_tokens_edit('tok2=new_value2;tok3=new_value3') |
- +--------------------------------------------------------+
- +--------------------------------------------------------+
version_tokens_set(
token_list
)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
pairs specifying the name of each token to be defined and its value. If the argument isname
=value
NULL
or a string containing no tokens, the token list is cleared.Returns the server's list of version tokens as a binary string containing a semicolon-separated list of
pairs.name
=value
- +--------------------------+
- | version_tokens_show() |
- +--------------------------+
- | tok2=value2;tok1=value1; |
- +--------------------------+
The following UDFs permit version tokens to be locked and unlocked:
version_tokens_lock_exclusive(
token_name
[,token_name
] ...,timeout
)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.
- +-----------------------------------------------------+
- | version_tokens_lock_exclusive('lock1', 'lock2', 10) |
- +-----------------------------------------------------+
- | 1 |
- +-----------------------------------------------------+
version_tokens_lock_shared(
token_name
[,token_name
] ...,timeout
)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.
- +--------------------------------------------------+
- | version_tokens_lock_shared('lock1', 'lock2', 10) |
- +--------------------------------------------------+
- | 1 |
- +--------------------------------------------------+
Releases all locks that were acquired within the current session using
version_tokens_lock_exclusive()
andversion_tokens_lock_shared()
.- +-------------------------+
- | 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 UDFs 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 29.3.1, “The Locking Service”.
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”).
System variables:
-
Property Value Command-Line Format --version-tokens-session=value
System Variable version_tokens_session
Scope Global, Session Dynamic Yes SET_VAR
Hint AppliesNo 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
variable isNULL
(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
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
value is not present in the server token list. In this case, anER_VTOKEN_PLUGIN_TOKEN_NOT_FOUND
error occurs.A token value in the
version_tokens_session
value differs from the value of the corresponding token in the server token list. In this case, anER_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
value.Suppose that a management application has set the server token list as follows:
- +--------------------------------------------+
- | version_tokens_set('tok1=a;tok2=b;tok3=c') |
- +--------------------------------------------+
- +--------------------------------------------+
A client registers the tokens it requires the server to match by setting its
version_tokens_session
value. Then, for each subsequent statement sent by the client, the server checks its token list against the clientversion_tokens_session
value and produces an error if there is a mismatch:- +---+
- | 1 |
- +---+
- | 1 |
- +---+
The first
SELECT
succeeds because the client tokenstok1
andtok2
are present in the server token list and each token has the same value in the server list. The secondSELECT
fails because, althoughtok1
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:
- +-------------------------------+
- | version_tokens_edit('tok1=b') |
- +-------------------------------+
- +-------------------------------+
- +-----------------------+
- | version_tokens_show() |
- +-----------------------+
- | tok3=c;tok1=b;tok2=b; |
- +-----------------------+
Now the client
version_tokens_session
value matches the server token list and the client can once again successfully execute statements:- +---+
- | 1 |
- +---+
- | 1 |
- +---+
-
Property Value Command-Line Format --version-tokens-session-number=#
System Variable version_tokens_session_number
Scope Global, Session Dynamic No SET_VAR
Hint AppliesNo Type Integer Default Value 0
This variable is for internal use.
Document created the 26/06/2006, last modified the 26/10/2018
Source of the printed document:https://www.gaudry.be/en/mysql-rf-version-tokens-reference.html
The infobrol is a personal site whose content is my sole responsibility. The text is available under CreativeCommons license (BY-NC-SA). More info on the terms of use and the author.
References
These references and links indicate documents consulted during the writing of this page, or which may provide additional information, but the authors of these sources can not be held responsible for the content of this page.
The author This site is solely responsible for the way in which the various concepts, and the freedoms that are taken with the reference works, are presented here. Remember that you must cross multiple source information to reduce the risk of errors.