> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyring Access and MySQL Services

> The vsql::preview::keyring capability reads and writes secrets in the MySQL keyring, and vsql::preview::mysql_services lets an extension consume MySQL registry services.

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](https://villagesql.com/docs/en/extensions/build/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](https://dev.mysql.com/doc/refman/8.4/en/keyring-component-installation.html);
`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()`:

| Status | Meaning |
| - | - |
| `Status::OK` | Operation succeeded. |
| `Status::NOT_FOUND` | The key does not exist (read only). |
| `Status::UNAVAILABLE` | No keyring component is installed. |
| `Status::ERROR` | Other failure. |

### Declaring the Capability

Include the header, declare a capability object at file scope, and pass it
to `.with()`:

```cpp theme={null}
#include <villagesql/preview/keyring.h>
#include <villagesql/vsql.h>

using KeyringCapability = vsql::preview_keyring::KeyringCapability;

static KeyringCapability g_keyring;

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .with(g_keyring))
```

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

```cpp theme={null}
struct KeyringCapability::ReadResult {
  KeyringCapability::Status status;
  std::string value;
};

[[nodiscard]] KeyringCapability::ReadResult
KeyringCapability::read(std::string_view data_id,
                        std::string_view auth_id = {}) const;

[[nodiscard]] KeyringCapability::Status
KeyringCapability::write(std::string_view data_id,
                         std::string_view auth_id,
                         std::string_view data) const;
```

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

```cpp theme={null}
auto [status, value] = g_keyring.read("my_secret");
if (status == KeyringCapability::Status::OK) {
  // value contains the secret bytes
}
```

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

```cpp theme={null}
#include <villagesql/preview/keyring.h>
#include <villagesql/vsql.h>

using namespace vsql;
using KeyringCapability = vsql::preview_keyring::KeyringCapability;

static KeyringCapability g_keyring;

void keyring_read(StringArg data_id, StringArg auth_id, StringResult out) {
  if (data_id.is_null()) { out.set_null(); return; }

  const auto [status, value] =
      g_keyring.read(data_id.value(), auth_id.is_null() ? "" : auth_id.value());
  if (status == KeyringCapability::Status::UNAVAILABLE) {
    out.error("No keyring component is installed");
    return;
  }
  if (status != KeyringCapability::Status::OK) { out.set_null(); return; }

  out.set(value);
}

void keyring_store(StringArg data_id, StringArg auth_id, StringArg value,
                   IntResult out) {
  if (data_id.is_null() || value.is_null()) { out.set(1); return; }

  KeyringCapability::Status status = g_keyring.write(
      data_id.value(), auth_id.is_null() ? "" : auth_id.value(), value.value());
  if (status == KeyringCapability::Status::UNAVAILABLE) {
    out.error("No keyring component is installed");
    return;
  }
  out.set(status == KeyringCapability::Status::OK ? 0 : 1);
}

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .func(make_func<&keyring_read>("keyring_read")
                  .returns(STRING).param(STRING).param(STRING).build())
        .func(make_func<&keyring_store>("keyring_store")
                  .returns(INT).param(STRING).param(STRING).param(STRING).build())
        .with(g_keyring))
```

## 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:

```cpp theme={null}
#include <cstddef>

#include <mysql/components/services/mysql_current_thread_reader.h>
#include <villagesql/preview/mysql_services.h>
#include <villagesql/vsql.h>

using namespace vsql;

static preview_mysql_services::MysqlServices services;
VSQL_REQUIRE_SERVICE(services, mysql_current_thread_reader, thd_reader);

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .func(/* ... */)
        .with(services))
```

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

```cpp theme={null}
static preview_mysql_services::ServiceRef<SERVICE_TYPE(keyring_reader_with_status)>
    reader;
static const int reader_req =
    (services.require<SERVICE_TYPE(keyring_reader_with_status)>(
         "keyring_reader_with_status.component_keyring_file", reader),
     0);
```

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:

| Include path | Provides |
| - | - |
| `<source>/include` | the service definitions, `mysql/components/services/*.h` |
| `<build>/include` | headers generated at build time, such as `mysqld_error.h` |

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):

```text theme={null}
error: unknown type name 'mysql_service_mysql_current_thread_reader_t'
```

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:

```text theme={null}
error: unknown type name 'size_t'
```

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:

```cpp theme={null}
if (!thd_reader.valid()) { out.error("service unavailable"); return; }
MYSQL_THD thd = nullptr;
if (thd_reader->get(&thd) || thd == nullptr) { out.set_null(); return; }
```

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:

```text theme={null}
ERROR 3219 (HY000): Failed to load VEF extension 'vsql_mysql_services_missing_test': failed to acquire MySQL service 'vsql_intentionally_missing'
```

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](https://villagesql.com/docs/en/extensions/build/preview-capabilities#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:

```cpp theme={null}
#include <cstddef>

#include <mysql/components/services/defs/mysql_string_defs.h>
#include <mysql/components/services/mysql_current_thread_reader.h>
#include <mysql/components/services/mysql_thd_attributes.h>
#include <villagesql/preview/mysql_services.h>
#include <villagesql/vsql.h>

using namespace vsql;

static preview_mysql_services::MysqlServices services;
VSQL_REQUIRE_SERVICE(services, mysql_current_thread_reader, thd_reader);
VSQL_REQUIRE_SERVICE(services, mysql_thd_attributes, attrs);

// session_sql_command() -> STRING: the name of the SQL command running on the
// calling session, or NULL when the THD or the attribute cannot be read.
void session_sql_command(StringResult out) {
  if (!thd_reader.valid() || !attrs.valid()) {
    out.error("MySQL session services are not available");
    return;
  }

  MYSQL_THD thd = nullptr;
  // MySQL convention: a false return means success.
  if (thd_reader->get(&thd) || thd == nullptr) {
    out.set_null();
    return;
  }

  mysql_cstring_with_length value{nullptr, 0};
  if (attrs->get(thd, "sql_command", &value) || value.str == nullptr) {
    out.set_null();
    return;
  }

  out.set(std::string_view(value.str, value.length));
}

VEF_GENERATE_ENTRY_POINTS(make_extension().with(services).func(
    make_func<&session_sql_command>("session_sql_command")
        .returns(STRING)
        .no_params()
        .build()))
```

Install it and call the function:

```sql theme={null}
INSTALL EXTENSION my_ext;
SELECT my_ext.session_sql_command() AS sql_command;
```

```text theme={null}
+-------------+
| sql_command |
+-------------+
| select      |
+-------------+
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.