> ## 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 접근 및 MySQL 서비스

> vsql::preview::keyring 기능은 MySQL 키링의 비밀 정보를 읽고 쓰며, vsql::preview::mysql_services 기능을 사용하면 확장 프로그램이 MySQL 레지스트리 서비스를 사용할 수 있습니다.

이 페이지의 기능은 미리보기 단계입니다. API는 안정적이지 않으며, 이 기능을 선언하는 확장 프로그램은 설치 시 `vsql_allow_preview_extensions = ON`이 필요합니다. 미리보기 계층을 활성화하고 기능을 등록하는 방법은 [미리보기 기능](https://villagesql.com/docs/ko/extensions/build/preview-capabilities)을 참조하세요.

## Keyring 접근

keyring 기능(`vsql::preview::keyring`)은 MySQL keyring 구성 요소에 저장된 비밀을 읽고 쓸 수 있게 해줍니다. 확장 프로그램은 API 키, 암호화 키 또는 SQL 테이블에 저장되지 않아야 하는 기타 비밀을 처리하는 데 사용합니다.

기능 이름 `VEF_PREVIEW_KEYRING_NAME`은 `"vsql::preview::keyring"`입니다.

keyring 구성 요소(예: `component_keyring_file`)는 [Keyring 구성 요소 설치](https://dev.mysql.com/doc/refman/8.4/en/keyring-component-installation.html)에 설명된 대로 구성 요소 매니페스트와 그 구성 파일을 통해 서버 시작 시 로드되어야 합니다. `INSTALL COMPONENT`로는 사용할 수 없습니다. 없으면 작업은 `KeyringCapability::Status::UNAVAILABLE`을 반환합니다.

### 상태 값

`KeyringCapability::Status`는 `read()`(내부 `ReadResult`에서) 및 `write()`에서 반환되는 범위화된 열거형입니다:

| 상태 | 의미 |
| - | - |
| `Status::OK` | 작업이 성공했습니다. |
| `Status::NOT_FOUND` | 키가 존재하지 않습니다(읽기 전용). |
| `Status::UNAVAILABLE` | keyring 구성 요소가 설치되지 않았습니다. |
| `Status::ERROR` | 기타 실패. |

### 기능 선언

헤더를 포함하고 파일 범위에서 기능 객체를 선언한 후 `.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))
```

`g_keyring` 객체는 서버가 로드 시 채웁니다. keyring 구성 요소가 설치되지 않은 경우 `read()` 및 `write()` 메서드는 런타임에 `Status::UNAVAILABLE`을 반환합니다 — 별도의 가용성 검사 대신 각 호출에서 상태를 확인하세요.

### 읽기 및 쓰기

```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`는 키 식별자입니다. `auth_id`는 소유 사용자입니다 — 내부 키(특정 사용자와 연결되지 않음)를 읽거나 쓰려면 빈 문자열(또는 `read`에서 생략, 기본값 `{}`)을 전달합니다.

`read`는 값으로 `ReadResult`를 반환합니다. 구조화된 바인딩으로 바인딩합니다:

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

`Status::OK`가 아닌 상태에서는 `value`가 비어 있습니다.

`write`는 `Status`를 직접 반환하고 `data`를 `data_id`/`auth_id` 아래에 저장합니다. `component_keyring_file`에서는 기존 키에 쓰면 `Status::ERROR`가 반환됩니다.

### 완전한 예제

이것은 서버의 `villagesql/test-extensions/` 트리에 있는 `vsql_keyring_reader` 테스트 확장 프로그램의 간단한 버전입니다. 이 확장 프로그램은 2개의 VDF를 등록합니다: `keyring_read` 및 `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; }

  auto buf = out.buffer();
  if (value.size() <= buf.size())
    memcpy(buf.data(), value.data(), value.size());
  out.set_length(value.size());
}

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 서비스

mysql\_services 기능(`vsql::preview::mysql_services`)은 확장 프로그램이 MySQL 레지스트리 서비스를 사용할 수 있게 해줍니다 — MySQL 구성 요소가 사용하는 것과 동일한 서비스로, 설치된 구성 요소 또는 서버 코어가 제공합니다. 확장 프로그램은 필요한 모든 서비스를 한곳에서 선언하고, 서버는 확장 프로그램이 로드될 때 각 서비스를 획득하고 확장 프로그램이 언로드될 때 해제합니다.

기능 이름 `VEF_PREVIEW_MYSQL_SERVICES_NAME`은 `"vsql::preview::mysql_services"`입니다.

서버 설비에 자체 VEF 기능이 없을 때 이것을 사용하세요. 세션 속성과 keyring 자체의 구성 요소 서비스는 모두 이 방식으로 접근할 수 있습니다. 사용만 지원됩니다: 확장 프로그램 자체의 구현을 레지스트리에 등록하는 것은 향후 계획된 작업이며 이 기능에 포함되지 않습니다.

### 기능 선언

파일 범위에서 하나의 `MysqlServices` 객체를 선언하고, 사용하는 각 서비스를 `VSQL_REQUIRE_SERVICE`로 지정한 후, 그 객체를 `.with()`에 전달합니다. 각 서비스에 대해 MySQL 자체 헤더를 포함하세요 — 해당 헤더가 서비스의 유형과 메서드를 선언하는 곳입니다:

```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)`은 서버가 획득한 서비스를 기록하는 참조인 `var`를 선언하고, `services`에 `name`을 등록합니다. 이 매크로는 `var`를 `static`으로 선언해 줍니다. `MysqlServices` 객체도 `static`이어야 하며, 직접 선언하는 모든 참조도 마찬가지입니다: 서버가 로드 시 이들을 통해 값을 기록하므로, 확장 프로그램보다 오래 유지되어야 합니다.

### 특정 구현 고정

`VSQL_REQUIRE_SERVICE`는 `name`을 두 번 사용합니다 — C++ `SERVICE_TYPE(name)`으로, 그리고 서버가 레지스트리에서 조회하는 문자열로. 이 단순 이름 아래에서 서버는 해당 서비스의 기본 구현을 획득합니다.

대신 하나의 구현을 지정하려면, MySQL의 `PROVIDES_SERVICE(component, service)`가 생성하는 형식인 정규화된 레지스트리 이름 `service.component`를 사용하세요. 다음은 기본 구현이 아니라 `component_keyring_file` 구성 요소의 keyring 리더를 요청합니다:

```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);
```

정규화된 이름은 단순 이름과 동일한 방식으로 획득되므로, 일반적인 규칙이 그대로 적용됩니다: 해당 구현이 정확히 등록되어 있지 않으면 확장 프로그램은 다른 구현으로 대체되지 않고 설치에 실패합니다.

### MySQL 헤더에 대해 빌드

서비스 정의는 VEF가 아니라 MySQL의 구성 요소 프레임워크에 속하며, 서버는 이를 설치하지 않습니다. 따라서 `mysql/components/services/*.h`는 확장 프로그램 SDK에도, `make install`이 빌드하는 어떤 것에도 없으며, 여기에는 릴리스 tarball과 Docker 이미지가 포함됩니다. 서비스를 사용하는 확장 프로그램은 VillageSQL 서버 소스 트리에 대해 빌드합니다:

| 포함 경로 | 제공 내용 |
| - | - |
| `<source>/include` | 서비스 정의, `mysql/components/services/*.h` |
| `<build>/include` | 빌드 시 생성되는 헤더, 예: `mysqld_error.h` |

인트리 테스트 확장 프로그램은 `vsql_add_test_extension()`의 `MYSQL_HEADERS` 플래그에서 둘 다 얻으며, 이 플래그는 이들을 `MYSQL_INCLUDE_DIR` 및 `MYSQL_GENERATED_INCLUDE_DIR`로 전달합니다. 아웃오브트리 빌드는 자체 포함 경로를 설정합니다.

두 가지 빌드 실패는 원인이 된 줄이 아닌 다른 곳에서 나타납니다.

서비스의 MySQL 헤더를 생략하면 `VSQL_REQUIRE_SERVICE`에 아무것도 해석되지 않는 이름이 남으므로, 오류는 누락된 include가 아니라 매크로에서 나타납니다(clang 17):

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

일부 서비스 정의는 `<cstddef>`를 포함하지 않고 `size_t`를 사용하므로, 그러한 헤더 중 하나를 모든 villagesql 헤더보다 앞에 두면 MySQL 자체 헤더 내부에서 실패합니다:

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

이 페이지의 예제처럼 `<cstddef>`를 먼저 포함하세요.

### 서비스 호출

서비스 참조는 자체적으로 `valid()`를 노출하며, `->`는 서비스로 전달됩니다. 참조에는 `.`를, 서비스에는 `->`를 사용하세요:

```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; }
```

모든 `->` 호출 전에 `valid()`를 확인하세요. `->`는 획득된 포인터를 반환하며, 서비스가 획득되지 않았을 때는 null입니다.

획득에 실패한 서비스는 설치를 실패시키므로, 실행 중인 함수 내부에서는 필요한 서비스가 유효합니다. 그럼에도 이 검사는 여전히 중요합니다. 직접 선언하고 `require()`에 전달하지 않은 `ServiceRef`에는 아무것도 기록되지 않기 때문입니다: 컴파일도 되고 확장 프로그램도 설치되지만, 확장 프로그램이 살아 있는 동안 `valid()`는 계속 false입니다.

서비스가 *무엇인지* — 그 메서드, 매개변수, 반환 값 — 는 여기가 아니라 MySQL이 문서화합니다. `NAME`이라는 서비스의 경우, 서버 트리의 `include/mysql/components/services/NAME.h`를 읽으세요: 그 안의 `BEGIN_SERVICE_DEFINITION(NAME)` 블록이 모든 메서드를 자체 문서와 함께 선언합니다. `bool` 반환에서 `false`가 성공을 의미하고 `true`가 실패를 의미한다는 MySQL의 관례를 포함하여, 해당 헤더가 명시하는 그대로 호출하세요.

### 획득 실패

선언된 모든 서비스는 확장 프로그램이 로드될 때, 즉 어떤 함수도 호출되기 전에 획득되므로, 등록되지 않은 서비스는 나중에 드러나지 않고 로드를 실패시킵니다. `INSTALL EXTENSION`이 실패하며 해당 서비스 이름을 명시합니다.

아래의 `vsql_mysql_services_missing_test`는 레지스트리에 없는 서비스를 요구하는 인트리 테스트 확장 프로그램입니다. 설치할 수 있는 것이 아니라 — 이 실패를 포착한 방법이며, 이 서버가 제공하지 않는 서비스를 요구할 때 여러분의 확장 프로그램이 생성하는 결과입니다:

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

다른 두 가지 설치 실패는 이 기능 밖에서 동일한 기능에 도달합니다: `MysqlServices` 객체를 `.with()`에서 빠뜨리는 경우, 그리고 `vsql_allow_preview_extensions`가 OFF인 서버에 설치하는 경우입니다. 둘 다 [등록 패턴](https://villagesql.com/docs/ko/extensions/build/preview-capabilities#registration-pattern)에서 다룹니다.

### 완전한 예제

서버의 `villagesql/test-extensions/` 트리에 있는 `vsql_mysql_services_session_test`의 간단한 버전입니다. 이는 두 서비스를 조합하여 호출 세션에서 실행 중인 SQL 명령을 읽습니다: 하나는 현재 `THD`를 반환하고, 다른 하나는 그 위에서 이름이 지정된 속성을 읽습니다. 둘 다 모든 서버에 등록되는 서버 코어 서비스이므로, 먼저 설치할 것이 없습니다:

```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()))
```

설치한 후 함수를 호출합니다:

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