Skip to main content
The capabilities on this page are in preview: their APIs are not stable, and an extension that declares one requires 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():
The 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:
On any status other than 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 the vsql_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 one MysqlServices 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:
A qualified name is acquired the same way as a bare one, so the usual rule applies: if that exact implementation is not registered, the extension fails to install rather than falling back to another one.

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):
Some service definitions use size_t without including <cstddef>, so putting one of those headers ahead of every villagesql header fails inside MySQL’s own header:
Include <cstddef> first, as the examples on this page do.

Calling a Service

A service reference exposes valid() of its own, and -> forwards to the service. Use . for the reference and -> for the service:
Check 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:
Two other install failures reach the same capability from outside it: leaving the 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 of vsql_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:
Install it and call the function: