vsql_allow_preview_extensions = ON to install. See Preview Capabilities for how to enable the preview tier and register a capability.
Status Variables
The status_var capability (vsql::status_var) lets an extension
expose long long and double counters as MySQL status variables. The
extension owns the storage and writes to it; the server reads through the
pointers each time the status variable is queried.
Build the capability with vsql::preview_status_var::make_capability(), passing
a braced list of descriptors from make_int(name, value_ptr) or
make_double(name, value_ptr). The template deduces the count from the
braced list, so no explicit size is required.
Complete Example
make_int requires a long long *; make_double requires a double *.
Those are the only two types supported.
Accessing from SQL
AfterINSTALL EXTENSION my_ext, the variable is visible with the extension
name as a prefix:
++ may
occasionally be lost; this is acceptable for approximate call counters exposed
via SHOW STATUS.
System Variables
The sys_var capability (vsql::sys_var) lets an extension register
MySQL system variables backed by extension-owned storage. Four types are
supported: BOOL (bool *), INT (long long *), STR (char **), and
ENUM (unsigned long *, storing a zero-based index
into a fixed, ordered list of names). INT descriptors also
carry min_val and max_val bounds; all descriptors carry a default value
and a comment.
Build the capability with vsql::preview_sys_var::make_capability() and the
matching factory functions make_bool, make_int, make_str, and
make_enum. The
capability object also exposes get() and set() for
programmatic access from extension code. Both return false on success.
To react to value changes, chain .on_change<&fn>() on a descriptor. The
callback receives a sv::SysVarChange with var_name() and typed accessors
(as_int(), as_str(), and as_enum()).
The server calls that callback while it holds its global system-variable lock.
Reading or writing another of this extension’s variables through its storage
pointer is safe there, and other sessions see the new value immediately, because
the server reads those variables under the same lock.
The capability object must have static storage duration. MySQL writes directly
to the storage pointers when the user sets a variable.
An enum variable is set by name (
SET GLOBAL my_ext.mode = 'sync') or by the
name’s zero-based index; either way the server validates the value against
names before accepting it, rejecting an unrecognized name or an
out-of-range index rather than storing it:
make_str: the
value space is closed and enforced at SET time. A convenience overload
deduces name_count from a static const char *const NAMES[] = {...} array,
so the count argument can be omitted.
Complete Example
Accessing from SQL
AfterINSTALL EXTENSION my_ext, variables are accessible using the extension
name as a component prefix:
Reading and Writing from Extension Code
For INT and BOOL variables, read the global storage pointer directly — MySQL updates those atomically. To update a variable through MySQL (so locking, range validation, and persistence are handled by the server), callSYS_VARS.set(extension_name, var_name, scope, value). Both set and get
return false on success. Neither can be called from an on_change callback:
both deadlock on the system-variable lock.
set and get take the extension and variable names as const char *. An INT variable is set only with an integer value; set with a string value fails (returns true) for an INT variable. Set BOOL, STRING, DOUBLE, and ENUM variables with a string value.
The scope argument controls persistence:
Session Variables
The session_var capability (vsql::session_var) lets an extension register
per-session (THD-local) system variables — the functional equivalent of a
plugin’s MYSQL_THDVAR_*. It is the session-scoped sibling of
vsql::sys_var: a sys_var has one value shared by every
connection, while a session_var gives each connection its own value, set with
SET SESSION. The starting point for a new session is the descriptor’s default, or the value last stored by SET GLOBAL. A variable’s scope is fixed
at registration — use this capability for per-session variables, vsql::sys_var
for global ones.
Only two types are supported: INT (long long) and STR (std::string).
There is no BOOL or DOUBLE session variable, and there is no on_change
callback mechanism — unlike vsql::sys_var, an extension observes a session
variable’s value only by reading it back, not by being notified when it
changes.
Declaring the Capability
Build the capability withvsql::preview_session_var::make_capability(),
passing a braced list of descriptors from make_int(name, comment) or
make_str(name, comment), each configured with the fluent .default_(),
.min(), and .max() setters (min/max apply to INT only):
make_int starts unconstrained (default 0, full long long range);
make_str starts with an empty-string default. The capability object needs
static storage duration, matching every other preview capability on this page.
Reading Session Values
There are two read paths, both resolved against the calling connection’s thread — so both must be called on the connection thread (a VDF or callback running on the connection), never from a background thread worker:SESSION_VARS.get_session_int(name, out)/get_session_str(name, out)— name-keyed, re-resolves the variable on every call. Use this for occasional reads, and forSTRvariables it is the only path: there is no lock-free string fast path, because aSTRslot holds a pointer to a separately allocated buffer that a concurrentSET SESSIONorUNINSTALLcan free.SESSION_VARS.int_var(name)returns anIntVarthat resolves itself lazily on its firstread()and caches the result, so it can be declared at file/static scope before the capability has loaded. Each subsequentread()is a lock-free per-thread offset load — no name lookup, no global lock — the equivalent of a plugin’sTHDVAR(thd, var). This fast path isINT-only.
Accessing from SQL
AfterINSTALL EXTENSION my_ext, each variable takes the extension name as a
component prefix and is readable/settable with both @@session. and
@@global.:
SET SESSION, and
sees the compiled default until it sets its own value; SET GLOBAL changes the
default that new or reset sessions pick up, not any session’s already-set
value.
Out-of-range INT assignments clamp to the bound and warn, and a wrong-typed
assignment is rejected, exactly as for an ordinary MySQL system variable:
Restart Behavior
SET PERSIST and SET PERSIST_ONLY work on a session variable’s global value as on any MySQL system
variable: the value survives a server restart, and each new session starts at it. A SET SESSION
value is per-connection state and does not survive a restart. Without SET PERSIST, each variable
reappears at its compiled default after a restart with the extension still installed.