vsql_allow_preview_extensions = ON to install. See Preview Capabilities for how to enable the preview tier and register a capability.
Keyring Access
The keyring capability (vsql::preview::keyring) lets extensions read and
write secrets stored in the MySQL keyring component. Extensions use it for
things like API keys, encryption keys, or other secrets that shouldn’t live
in SQL tables.
The capability name VEF_PREVIEW_KEYRING_NAME is "vsql::preview::keyring".
A keyring component (for example component_keyring_file) must be loaded
at server startup through a component manifest and its configuration file, as described in
Keyring Component Installation;
INSTALL COMPONENT does not make it available. Without one, operations return
KeyringCapability::Status::UNAVAILABLE.
Status Values
KeyringCapability::Status is a scoped enum returned by read() (inside
ReadResult) and write():
Declaring the Capability
Include the header, declare a capability object at file scope, and pass it to.with():
g_keyring object is populated by the server at load time. The
read() and write() methods return Status::UNAVAILABLE at runtime
when no keyring component is installed — check that status on each call
rather than gating on a separate availability probe.
Reading and Writing
data_id is the key identifier. auth_id is the owning user — pass an
empty string (or omit it on read, which defaults to {}) to read or write
internal keys not associated with a specific user.
read returns a ReadResult by value. Bind it with structured bindings:
Status::OK, value is empty.
write returns Status directly and stores data under data_id /
auth_id. With component_keyring_file, writing an existing key returns Status::ERROR.
Complete Example
This is a simplified version of thevsql_keyring_reader test extension, in
the server’s villagesql/test-extensions/ tree. It registers 2 VDFs:
keyring_read and keyring_store.
MySQL Services
The mysql_services capability (vsql::preview::mysql_services) lets an
extension consume MySQL registry services — the same services a MySQL component
consumes, provided either by an installed component or by the server core. The
extension declares every service it needs in one place; the server acquires each
one when the extension loads and releases it when the extension unloads.
The capability name VEF_PREVIEW_MYSQL_SERVICES_NAME is
"vsql::preview::mysql_services".
Reach for it when a server facility has no VEF capability of its own. Session
attributes and the keyring’s own component services are both reachable this
way. Only consuming is supported: registering the extension’s own
implementation into the registry is a planned follow-up and is not part of this
capability.
Declaring the Capability
Declare oneMysqlServices object at file scope, name each service you consume
with VSQL_REQUIRE_SERVICE, and pass the object to .with(). Include MySQL’s
own header for each service — that header is where the service’s type and
methods are declared:
VSQL_REQUIRE_SERVICE(services, name, var) declares var, the reference the
server writes the acquired service into, and registers name on services. It
declares var static for you. The MysqlServices object needs to be static
too, and so does any reference you declare by hand: the server writes through
them at load, and they must outlive the extension.
Pinning a Specific Implementation
VSQL_REQUIRE_SERVICE uses name twice — as the C++ SERVICE_TYPE(name) and
as the string the server looks up in the registry. Under that bare name the
server acquires the service’s default implementation.
To name one implementation instead, use its qualified registry name —
service.component, the form MySQL’s PROVIDES_SERVICE(component, service)
generates. This asks for the keyring reader from the component_keyring_file
component rather than for the default:
Building Against MySQL’s Headers
Service definitions belong to MySQL’s component framework rather than to VEF, and the server does not install them.mysql/components/services/*.h is
therefore absent from the extension SDK and from anything built by
make install, which includes the release tarball and the Docker image. An
extension that consumes services builds against a VillageSQL server source
tree:
The in-tree test extensions get both from the
MYSQL_HEADERS flag on
vsql_add_test_extension(), which passes them as MYSQL_INCLUDE_DIR and
MYSQL_GENERATED_INCLUDE_DIR. An out-of-tree build sets its own include paths.
Two build failures land somewhere other than the line that caused them.
Omitting a service’s MySQL header leaves VSQL_REQUIRE_SERVICE with a name
that resolves to nothing, so the error appears on the macro rather than on the
missing include (clang 17):
size_t without including <cstddef>, so putting
one of those headers ahead of every villagesql header fails inside MySQL’s own
header:
<cstddef> first, as the examples on this page do.
Calling a Service
A service reference exposesvalid() of its own, and -> forwards to the
service. Use . for the reference and -> for the service:
valid() before every -> call. -> returns the acquired pointer, which
is null when the service was not acquired.
A service that fails to acquire fails the install, so inside a function that is
running, a required service is valid. The check still matters, because a
ServiceRef declared by hand and never passed to require() is never written
to: it compiles, the extension installs, and valid() is false for the life of
the extension.
What a service is — its methods, their parameters, and what they return — is
documented by MySQL rather than here. For a service named NAME, read
include/mysql/components/services/NAME.h in the server tree: its
BEGIN_SERVICE_DEFINITION(NAME) block declares every method with its own
documentation. Call them exactly as that header specifies, including MySQL’s
convention that a bool return of false means success and true means
failure.
Acquisition Failure
Every declared service is acquired when the extension loads, before any of its functions can be called, so a service that is not registered fails the load rather than surfacing later.INSTALL EXTENSION fails and names the service.
vsql_mysql_services_missing_test below is an in-tree test extension that
requires a service the registry does not have. It is not something you can
install — it is how the failure was captured, and what your own extension
produces if it requires a service this server does not provide:
MysqlServices object out of .with(), and installing on a server with
vsql_allow_preview_extensions OFF. Both are covered under
Registration Pattern.
Complete Example
A simplified version ofvsql_mysql_services_session_test, in the server’s
villagesql/test-extensions/ tree. It reads the SQL command running on the
calling session by composing two services: one hands back the current THD,
the other reads a named attribute off it. Both are server-core services
registered on every server, so nothing has to be installed first: