> ## 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, status_var, sys_var, thread_worker, sql_query 및 statement_event 기능, 그리고 등록 패턴을 다룹니다. 미리보기 기능은 API가 최종화되기 전에 확장 프로그램에 노출되는 서버 제공 기능입니다. 미리보기 기능을 선언하는 확장 프로그램은 설치 시 `vsql_allow_preview_extensions = ON`이 필요합니다 (참조: [미리보기 계층 활성화](#enabling-the-preview-tier)) — 미리보기 기능을 사용하지 않는 확장 프로그램은 이 설정과 무관하게 일반적으로 설치됩니다. 미리보기 기능 API는 안정적이지 않습니다. 미리보기 기능을 기반으로 빌드된 확장 프로그램은 서버 업데이트 후 로드에 실패할 수 있습니다. 기능이 안정화되면 헤더가 버전화된 안정적 C++ SDK 경로로 이동합니다.

미리보기 계층 활성화

미리보기 기능을 사용하는 확장 프로그램을 설치하기 전에 `vsql_allow_preview_extensions = ON`을 `SET PERSIST`로 설정합니다: ```sql theme={null} SET PERSIST vsql_allow_preview_extensions = ON; ``` `SET GLOBAL`은 이 변수에 대해 거부됩니다 — 서버는 설정이 재시작 후에도 유지되도록 하기 위해 `SET PERSIST`를 요구합니다. 미리보기 기능을 사용하는 확장 프로그램은 시작 시 로드되므로, 서버가 시작될 때 이 변수가 ON이어야 합니다. mysqld를 직접 실행하는 경우(예: 서버를 처음 시작하는 설치 스크립트에서), `mysqld-auto.cnf`가 아직 존재하지 않아 지속된 값을 저장할 수 없으므로 명령줄 플래그를 전달합니다: ```bash theme={null} mysqld --vsql_allow_preview_extensions=ON ``` 비활성화하려면: ```sql theme={null} SET PERSIST vsql_allow_preview_extensions = OFF; ``` 미리보기 기능을 사용하는 확장 프로그램이 현재 설치되어 있으면 이 설정을 비활성화하는 작업이 실패합니다. 먼저 해당 확장 프로그램을 제거한 후 설정을 끄세요. ## 기능 인덱스 | 기능 | 헤더 | 상태 | | -------------------------------- | ---------------------------------------- | ---- | | `vsql::preview::column_store` | `` | 미리보기 | | `vsql::preview::keyring` | `` | 미리보기 | | `vsql::preview::sql_query` | `` | 미리보기 | | `vsql::preview::statement_event` | `` | 미리보기 | | `vsql::preview::status_var` | `` | 미리보기 | | `vsql::preview::storage` | `` | 미리보기 | | `vsql::preview::sys_var` | `` | 미리보기 | | `vsql::preview::thread_worker` | `` | 미리보기 | ## 등록 패턴 미리보기 기능을 사용하려면 파일 범위에서 값으로 기능 객체를 선언하고, `make_extension()` 내부의 `.with()`에 참조로 전달합니다. 서버는 등록 중에 객체의 `abi` 포인터를 채웁니다: ```cpp theme={null} #include #include using KeyringCapability = vsql::preview_keyring::KeyringCapability; static KeyringCapability g_keyring; VEF_GENERATE_ENTRY_POINTS( make_extension() .func(/* ... */) .with(g_keyring)) ``` `.with(capability)`은 서버에 확장 프로그램이 필요한 기능을 알립니다. `vsql_allow_preview_extensions`가 OFF 상태에서 확장 프로그램이 설치되면, 서버는 해당 기능 이름을 명시한 오류와 함께 설치를 거부합니다. 확장 프로그램 내에서 선언된 모든 기능 객체는 정확히 한 번 `.with()`에 전달되어야 합니다. 로드 시 서버는 선언된 모든 기능 인스턴스를 `.with()`가 받은 내용과 비교하고 규칙을 위반하면 `INSTALL EXTENSION`을 실패시킵니다: * **선언되었으나 `.with()`에 전달되지 않은 경우:** `capability '' was declared but never passed to .with(); every CapabilityBase-derived static must be registered via .with(cap) in the extension builder` * **동일한 인스턴스가 `.with()`에 두 번 이상 전달된 경우:** `capability '' passed to .with() more than once` * **`.with()`에 전달된 객체가 기능이 아닌 경우:** `.with() received an object that does not inherit vsql::detail::CapabilityBase; not a registered capability` 전체 오류는 다음과 같이 표시됩니다: `Failed to load VEF extension '': vef_register returned an error: `.

Keyring 접근

keyring 기능(`vsql::preview::keyring`)은 MySQL keyring 구성 요소에 저장된 비밀을 읽고 쓸 수 있게 해줍니다. 확장 프로그램은 API 키, 암호화 키 또는 SQL 테이블에 저장되지 않아야 하는 기타 비밀을 처리하는 데 사용합니다. 기능 이름 `VEF_PREVIEW_KEYRING_NAME`은 `"vsql::preview::keyring"`입니다. 읽기와 쓰기 작업이 성공하려면 MySQL 서버에 keyring 구성 요소가 설치되어야 합니다. 없으면 작업은 `KeyringCapability::Status::UNAVAILABLE`을 반환합니다. ### 상태 값 `KeyringCapability::Status`는 `read()`(내부 `ReadResult`에서) 및 `write()`에서 반환되는 범위화된 열거형입니다: | 상태 | 의미 | | --------------------- | -------------------------- | | `Status::OK` | 작업이 성공했습니다. | | `Status::NOT_FOUND` | 키가 존재하지 않습니다(읽기 전용). | | `Status::UNAVAILABLE` | keyring 구성 요소가 설치되지 않았습니다. | | `Status::ERROR` | 기타 실패. | ### 기능 선언 헤더를 포함하고 파일 범위에서 기능 객체를 선언한 후 `.with()`에 전달합니다: ```cpp theme={null} #include #include 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` 아래에 저장합니다. ### 완전한 예제 이것은 서버와 함께 제공되는 `vsql_keyring_reader` 테스트 확장 프로그램의 간단한 버전입니다. 이 확장 프로그램은 2개의 VDF를 등록합니다: `keyring_read` 및 `keyring_store`. ```cpp theme={null} #include #include 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(); size_t len = std::min(value.size(), buf.size()); memcpy(buf.data(), value.data(), len); out.set_length(len); } 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)) ```

상태 변수

status\_var 기능(`vsql::preview::status_var`)은 확장 프로그램이 MySQL 상태 변수로 `long long` 및 `double` 카운터를 노출할 수 있게 해줍니다. 확장 프로그램은 저장소를 소유하고 쓰며, 서버는 상태 변수가 쿼리될 때마다 포인터를 통해 읽습니다. `vsql::preview_status_var::make_capability()`으로 기능을 구축하고, `make_int(name, value_ptr)` 또는 `make_double(name, value_ptr)`에서 제공하는 디스크립터 목록을 중괄호로 감싸 전달합니다. 템플릿은 중괄호 목록에서 개수를 추론하므로 명시적 크기는 필요하지 않습니다. ### 완전한 예제 ```cpp theme={null} #include #include namespace sv = vsql::preview_status_var; static long long g_hits = 0; static long long g_misses = 0; static auto STATUS_VARS = sv::make_capability({ sv::make_int("ext_hits", &g_hits), sv::make_int("ext_misses", &g_misses)}); VEF_GENERATE_ENTRY_POINTS( make_extension() .with(STATUS_VARS)) ``` `make_int`는 `long long *`를 요구하며, `make_double`는 `double *`를 요구합니다. 이 두 유형만 지원됩니다. ### SQL에서 접근 `INSTALL EXTENSION my_ext` 후, 변수는 확장 프로그램 이름을 접두사로 사용하여 사용 가능합니다: ```sql theme={null} SHOW GLOBAL STATUS LIKE 'my_ext%'; ``` ``` Variable_name Value my_ext.ext_hits 0 my_ext.ext_misses 0 ``` 다중 쿼리 스레드에서 비원자적 `++`를 사용해 동시 증가가 때로 손실될 수 있지만, 이는 `SHOW STATUS`를 통해 노출된 근사 호출 카운터에 대해 허용됩니다.

시스템 변수

sys\_var 기능(`vsql::preview::sys_var`)은 확장 프로그램이 소유한 저장소를 기반으로 하는 MySQL 시스템 변수를 등록할 수 있게 해줍니다. 세 가지 유형이 지원됩니다: `BOOL`(`bool *`), `INT`(`long long *`), `STR`(`char **`). `INT` 디스크립터는 `min_val` 및 `max_val` 경계를 포함하며, 모든 디스크립터는 기본값과 주석을 포함합니다. `vsql::preview_sys_var::make_capability()`으로 기능을 구축하고, 대응하는 팩토리 함수인 `make_bool`, `make_int`, `make_str`을 사용합니다. 기능 객체는 확장 코드에서의 프로그래밍 접근을 위해 `get()` 및 `set()`을 노출합니다. 둘 다 성공 시 `false`를 반환합니다. 값 변경에 반응하려면 디스크립터에 `.on_change<&fn>()`을 연결합니다. 콜백은 `var_name()` 및 타입 접근자(`as_int()`, `as_real()`, `as_str()`)를 포함하는 `sv::SysVarChange`를 수신합니다. 기능 객체는 정적 저장 기간을 가져야 합니다. MySQL은 사용자가 변수를 설정할 때 저장소 포인터에 직접 씁니다. | 팩토리 | 저장소 유형 | 추가 매개변수 | | --------------- | ------------- | ------------------------------- | | `sv::make_bool` | `bool *` | `def_val` | | `sv::make_int` | `long long *` | `def_val`, `min_val`, `max_val` | | `sv::make_str` | `char **` | `def_val` | ### 완전한 예제 ```cpp theme={null} #include #include namespace sv = vsql::preview_sys_var; static bool g_enabled = true; static long long g_threshold = 1000; static char *g_log_file = nullptr; static void on_threshold_change(sv::SysVarChange c) { // c.var_name() identifies the variable; c.as_int() returns the new value } static auto SYS_VARS = sv::make_capability({ sv::make_bool("enabled", "Enable feature", &g_enabled, true), sv::make_int ("threshold_ms", "Threshold in ms", &g_threshold, 1000, 0, 3600000) .on_change<&on_threshold_change>(), sv::make_str ("log_file", "Log file path", &g_log_file, "/tmp/myext.log")}); VEF_GENERATE_ENTRY_POINTS( make_extension() .with(SYS_VARS)) ``` ### SQL에서 접근 `INSTALL EXTENSION my_ext` 후, 변수는 확장 프로그램 이름을 구성 접두사로 사용하여 접근 가능합니다: ```sql theme={null} SELECT @@global.my_ext.threshold_ms; SET GLOBAL my_ext.threshold_ms = 500; SET GLOBAL my_ext.log_file = '/var/log/myext.log'; ``` ### 확장 코드에서 읽기 및 쓰기 INT 및 BOOL 변수의 경우, 전역 저장소 포인터를 직접 읽습니다 — MySQL은 이들을 원자적으로 업데이트합니다. MySQL을 통해 변수를 업데이트하려면(잠금, 범위 검증, 지속성이 서버에서 처리되도록), `SYS_VARS.set(extension_name, var_name, scope, value)`를 호출합니다. `set` 및 `get` 둘 다 성공 시 `false`를 반환합니다. ```cpp theme={null} bool err = SYS_VARS.set("my_ext", "threshold_ms", nullptr, value); ``` `scope` 인수는 다음과 같이 지속성을 제어합니다: | 범위 | 동작 | | ---------------- | ------------------------------------ | | `nullptr` | 실행 중 값만 업데이트, 지속되지 않음. | | `"PERSIST"` | 실행 중 값과 `mysqld-auto.cnf`에 쓰기. | | `"PERSIST_ONLY"` | `mysqld-auto.cnf`에만 쓰기; 다음 재시작 시 적용. | ## 스레드 워커 thread\_worker 기능(`vsql::preview::thread_worker`)은 확장 프로그램이 서버가 제어하는 백그라운드 스레드를 실행할 수 있게 해줍니다. 스레드는 서버가 확장 프로그램 로드 시 등록하는 제어 시스템 변수를 통해 시작 및 중지되며, 서버는 주기적 타이머, 파일 디스크립터 준비, 또는 활성/비활성 이벤트에 반응하여 확장 프로그램의 작업 함수를 호출합니다. 기능 이름 `VEF_PREVIEW_THREAD_WORKER_NAME`은 `"vsql::preview::thread_worker"`입니다. ### 기능 선언 헤더를 포함하고, 파일 범위에서 작업 함수로 인스턴스화된 `ThreadWorkerCapability`을 선언하고, `.with()`에 전달합니다: ```cpp theme={null} #include #include static vef_next_wakeup_t my_work(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg) { // ... return {}; } static vsql::preview_thread_worker::ThreadWorkerCapability<&my_work> g_worker{"suffix"}; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_worker)) ``` 작업 함수는 비유형 템플릿 인수(`ThreadWorkerCapability<&my_work>`)로 제공되므로, 다음 서명을 가진 함수여야 합니다. 첫 번째 생성자 인수는 스레드 이름 접미사이며, 선택적 두 번째 인수는 제어 시스템 변수 이름을 오버라이드합니다. ### 작업 함수 서명 ```c theme={null} typedef vef_next_wakeup_t (*vef_work_fn_t)(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg); ``` `reason`은 서버가 함수를 호출한 이유를 나타냅니다. `thread`는 이 워커에 대한 서버 소유 핸들입니다(초기 `VEF_WAKEUP_ENABLE` 호출 시 NULL — 아래 참조). `arg`는 디스크립터에 등록된 불명확한 포인터이며, 변경 없이 전달됩니다. ### 웨이크업 라이프사이클 서버는 다음 네 가지 이유 중 하나로 작업 함수를 호출합니다: | 이유 | 의미 | | --------------------- | ----------------------------------------------------------------------------- | | `VEF_WAKEUP_ENABLE` | 워커가 방금 활성화되었습니다(제어 시스템 변수가 ON으로 전환됨). 반환 값은 초기 `poll_fd` 및 `sleep_ms`를 설정합니다. | | `VEF_WAKEUP_PERIODIC` | 주기적 타이머가 발동되었습니다(`sleep_ms` 경과). | | `VEF_WAKEUP_POLL_FD` | 감시 중인 파일 디스크립터가 읽을 수 있게 되었습니다. | | `VEF_WAKEUP_DISABLE` | 워커 비활성화(제어 시스템 변수 OFF) 또는 서버 종료. 반환 값은 무시됩니다. | `reason`이 `VEF_WAKEUP_ENABLE`인 경우 `thread` 매개변수는 NULL입니다. 이 시점에는 스레드 핸들이 아직 존재하지 않기 때문입니다. 다른 세 가지 이유에 대해서는 `thread`가 NULL이 아닙니다. ### 웨이크업 반환 값 ```c theme={null} typedef struct { unsigned int sleep_ms; int poll_fd; } vef_next_wakeup_t; ``` 작업 함수는 `vef_next_wakeup_t`를 반환하여 다음 웨이크업 구성 설정을 업데이트합니다. 각 필드의 0 값은 "현재 설정 유지"를 의미합니다 — 변경하지 않으려면 구조체를 기본값으로 초기화하여 반환(`return {};`)하세요. 새로운 poll 파일 디스크립터를 설정하려면 해당 값을 반환합니다(0보다 커야 함). 기존 poll 파일 디스크립터를 제거하려면 `poll_fd`에 `-1`을 반환합니다. `reason`이 `VEF_WAKEUP_DISABLE`인 경우 반환 값은 무시됩니다. ### 스레드 이름 및 제어 변수 디스크립터의 두 필드가 이름을 제어합니다: * `suffix` — 스레드 이름 접미사. 서버는 확장 프로그램 이름을 접두사로 추가하여 `my_ext/monitor`와 같은 스레드 이름을 생성합니다. * `var_name` — 선택적. NULL이 아닌 경우 서버는 이 정확한 이름을 제어 시스템 변수로 등록합니다. NULL인 경우 서버는 기본 패턴 `{suffix}_enabled`을 사용합니다. 제어 변수는 서버가 등록한 시스템 변수입니다. `SET GLOBAL {suffix}_enabled = ON`으로 워커를 활성화하고, `OFF`로 설정하여 중지합니다. ### 완전한 예제 주기적 워커가 하나 있는 최소 확장 프로그램으로, 각 타이머 틱마다 심장 박동 카운터를 증가시킵니다. ```cpp theme={null} #include #include #include static std::atomic g_heartbeat{0}; static vef_next_wakeup_t heartbeat_work(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg) { switch (reason) { case VEF_WAKEUP_ENABLE: return {1000, 0}; // tick every 1000 ms, no poll fd case VEF_WAKEUP_PERIODIC: g_heartbeat.fetch_add(1, std::memory_order_relaxed); return {}; // keep current sleep_ms and poll_fd case VEF_WAKEUP_POLL_FD: return {}; // not used in this example case VEF_WAKEUP_DISABLE: return {}; // ignored } return {}; } static vsql::preview_thread_worker::ThreadWorkerCapability<&heartbeat_work> g_worker{"heartbeat"}; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_worker)) ``` 이 확장 프로그램을 설치한 후(`vsql_allow_preview_extensions = ON`), 서버는 `heartbeat_enabled` 시스템 변수를 등록합니다. 워커를 활성화하려면: ```sql theme={null} SET GLOBAL heartbeat_enabled = ON; ``` ## SQL 쿼리 sql\_query 기능(`vsql::preview::sql_query`)은 확장 프로그램이 백그라운드 스레드에서 SQL 문을 실행할 수 있게 해줍니다. 쿼리는 확장 프로그램이 MySQL 클라이언트 라이브러리에 링크하지 않고 기능 vtable을 통해 서버 내부에서 실행됩니다. 기능 이름 `VEF_PREVIEW_SQL_QUERY_NAME`은 `"vsql::preview::sql_query"`입니다. SQL 세션은 스레드 워커 콜백에서 해당 콜백의 `vef_thread_handle_t *`를 사용하여 열어야 합니다. `open()`은 VDF 또는 임의의 확장 프로그램 생성 스레드에서 유효하지 않습니다 — 워커 세션 컨텍스트가 필요합니다. ### 기능 선언 헤더를 포함하고, 파일 범위에서 `SqlQueryCapability`을 선언한 후 `.with()`에 전달합니다. 세션은 워커 콜백에서 열리므로, 일반적으로 `ThreadWorkerCapability`과 함께 등록됩니다: ```cpp theme={null} #include #include #include static vsql::preview_sql_query::SqlQueryCapability g_sql; static vef_next_wakeup_t my_work(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg) { auto session = g_sql.open(thread); if (!session) return {}; // ... return {}; } static vsql::preview_thread_worker::ThreadWorkerCapability<&my_work> g_worker{"sql_demo"}; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_worker) .with(g_sql)) ``` `g_sql.open(handle)`은 `Session`을 반환합니다. 사용 전에 `operator bool`로 확인하세요. 유효하지 않은 `Session`은 기능 vtable이 바인딩되지 않았거나 서버가 세션을 할당하지 못했음을 나타냅니다. `Session`은 이동 전용이며 소멸 시 자동으로 닫힙니다. ### 쿼리 실행 `Session`은 `session.sql(sv)`를 통해 `SqlQuery`를 생성합니다. 쿼리는 두 가지 모드로 실행할 수 있습니다: * `execute()` — 문을 실행하고 전체 결과 세트를 `Result`에 버퍼링합니다. 호출자의 속도에 맞춰 `next()`를 호출하여 행을 반복합니다. * `for_each(fn)` — 문을 실행하고 행이 생성될 때마다 `fn`을 한 번 호출합니다(버퍼링 없음). 반환된 `Result`는 진단 정보만 포함합니다(행 없음). 둘 다 `Result`를 반환합니다. `Result`가 null이 아닌 경우 문이 성공했다는 의미가 아닙니다 — `has_error()`를 호출하여 확인하세요. 버퍼링(`execute`): ```cpp theme={null} auto result = session.sql("SELECT id, name FROM t").execute(); if (result.has_error()) { // result.error().message holds the server error string. return {}; } while (result.next()) { long long id = result.column_int(0); std::string_view name = result.column_str(1); // ... } ``` `column_str()`은 `next()` 호출 또는 `Result` 소멸 전까지 유효한 `string_view`를 반환합니다. 더 긴 수명이 필요한 경우 복사하세요. `data() == nullptr`인 `string_view`는 SQL NULL을 나타냅니다. 스트리밍(`for_each`): ```cpp theme={null} auto status = session.sql("SELECT 1").for_each( [](const auto &row) { // row.column_int(0), row.column_str(1), etc. }); if (status.has_error()) { // status.error().message } ``` 콜백에 전달된 `Row`는 호출 기간 동안만 유효합니다 — 행 간에 참조를 저장하지 마세요. `for_each`가 반환한 `Result`는 버퍼링된 행을 보유하지 않습니다. `next()`는 데이터를 생성하지 않습니다. `has_error()`, `error()`, `warning_count()`, `warning(i)`에만 사용하세요. ### 진단 `execute()` 및 `for_each()`는 반환된 `Result`를 통해 진단을 표시합니다. 진단은 하나의 `Diag`입니다: ```cpp theme={null} struct Diag { uint32_t errno_; vef_sql_diag_severity_t severity; // NOTE | WARNING | ERROR std::string_view sqlstate; // 5-char SQLSTATE std::string_view message; // may be empty }; ``` | 필드 | 의미 | | ---------- | --------------------------------------------------------------------- | | `errno_` | MySQL 오류 번호. 오류가 없을 때 반환되는 기본 생성된 `Diag`에서는 `0`입니다. | | `severity` | `VEF_SQL_DIAG_NOTE`, `VEF_SQL_DIAG_WARNING`, 또는 `VEF_SQL_DIAG_ERROR`. | | `sqlstate` | 5자리 SQLSTATE. | | `message` | 서버가 제공한 진단 메시지; 비어 있을 수 있습니다. | `Result`는 다음과 같이 노출합니다: ```cpp theme={null} bool Result::has_error() const; Diag Result::error() const; unsigned int Result::warning_count() const; Diag Result::warning(unsigned int i) const; ``` `error()`는 문이 성공했을 때 기본 생성된 `Diag`(`errno_ == 0`)을 반환합니다. `warning(i)`는 `i >= warning_count()`일 때 기본 생성된 `Diag`를 반환합니다. `sqlstate` 및 `message` 뷰는 `Result`가 소유하는 저장소를 가리키며 `Result`가 소멸될 때 무효화됩니다 — 이들이 `Result`보다 오래 유지되어야 할 경우 복사하세요. ### 완전한 예제 각 틱마다 버퍼링 쿼리와 스트리밍 쿼리를 실행하고, 두 쿼리에서 진단을 로깅하는 워커: ```cpp theme={null} #include #include #include static vsql::preview_sql_query::SqlQueryCapability g_sql; static vef_next_wakeup_t sql_demo_work(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg) { if (reason == VEF_WAKEUP_ENABLE) return {5000, 0}; if (reason != VEF_WAKEUP_PERIODIC) return {}; auto session = g_sql.open(thread); if (!session) return {}; // Buffered: read a small result set. auto rs = session.sql("SELECT id, name FROM mydb.t LIMIT 10").execute(); if (rs.has_error()) { auto e = rs.error(); // Log e.errno_, e.sqlstate, e.message somewhere extension-owned. } else { while (rs.next()) { long long id = rs.column_int(0); std::string_view name = rs.column_str(1); (void)id; (void)name; } } // Streaming: process rows without buffering. auto status = session.sql("SELECT v FROM mydb.t").for_each( [](const auto &row) { long long v = row.column_int(0); (void)v; }); for (unsigned i = 0; i < status.warning_count(); ++i) { auto w = status.warning(i); (void)w; } return {}; } static vsql::preview_thread_worker::ThreadWorkerCapability<&sql_demo_work> g_worker{"sql_demo"}; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_worker) .with(g_sql)) ```

컬럼 저장

컬럼 저장은 확장 프로그램이 InnoDB에 직접 커스텀 유형의 이진 디스크 레이아웃을 등록할 수 있게 해줍니다. 이는 VARBINARY 페이로드를 통해 유형 바이트를 라우팅하는 대신, 커스텀 유형의 디스크 모양을 VARBINARY가 표현할 수 없는 경우(예: 전용 페이지에 저장되어야 하는 밀집된 부동 소수점 배열)에 사용됩니다. 이는 미리보기 기능(Capability)입니다: 기존 레이아웃에 대한 튜닝 장치가 아닌 새로운 저장 레이아웃을 활성화합니다. 컬럼 저장은 미리보기 ABI입니다 — 개발 중이며 릴리스 간에 변경될 수 있습니다. 현재는 행 수준 지속성만 지원하며, 커스텀 저장 컬럼에 대한 인덱싱은 아직 사용할 수 없습니다. ### 기능 선언 두 개의 미리보기 기능이 함께 작동합니다: * `vsql::preview::storage` — InnoDB 저장소 인프라구조(미니 트랜잭션, 세그먼트, 페이지)에 접근합니다. 파일 범위에서 `StorageCapability`을 선언합니다. * `vsql::preview::column_store` — 확장 프로그램의 커스텀 유형 중 하나에 대한 저장 구현을 바인딩합니다. `make_column_store(TYPE).…build()`를 사용하여 파일 범위에서 `ColumnStoreCapability`을 선언합니다. 둘 다 `make_extension()`의 `.with()`에 전달되어야 합니다: ```cpp theme={null} #include #include #include namespace storage = vsql::preview_storage; using vsql::preview_storage_builder::ColumnStoreCapability; using vsql::preview_storage_builder::make_column_store; using vsql::preview_storage_builder::StorageCapability; struct MyCtx { storage::Space::Ref space = 0; storage::Segment::PageRef root_page = storage::Page::INVALID_REF; }; static auto STORAGE = StorageCapability{}; static constexpr auto kMyStorage = make_column_store(MY_TYPE) .create<&MyStorage::create>() .drop<&MyStorage::drop>() .load<&MyStorage::load>() .insert<&MyStorage::insert>() .select<&MyStorage::select>() .mark_delete<&MyStorage::mark_delete>() .purge<&MyStorage::purge>() .build(); static auto COLUMN_STORE = ColumnStoreCapability().column_store(kMyStorage); using namespace vsql; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(STORAGE) .with(COLUMN_STORE) .type(MY_TYPE)) ``` `make_column_store(MY_TYPE)`은 구현을 동일한 확장 프로그램에서 등록된 하나의 커스텀 유형과 연결합니다. 모든 7개의 슬롯은 `build()` 시점에 필수적입니다. 각 슬롯은 InnoDB가 정상 운영 중에 도달하는 고유한 컬럼 라이프사이클 단계를 나타내기 때문입니다. ### 일곱 개의 저장 함수 모든 함수는 `storage::Column::StorageCtx*`를 받습니다. 이 `user()` 접근자는 확장 프로그램의 컬럼별 상태를 반환하고, `arena()`는 보조 개체에 대한 서버 관리 할당을 제공합니다. 모든 함수는 성공 시 `false`를 반환하고, 오류 시 `true`를 반환하며, `error_msg`(용량 `error_msg_len`)에 메시지를 작성하여 SQL 클라이언트에 표시합니다. ```cpp theme={null} // CREATE TABLE / ALTER TABLE ADD COLUMN. // col_len is the type's persisted length. Reserve segments here and store // space + root_page in ctx->user() so DML functions can reach them. bool create(storage::Column::StorageCtx*, storage::Space::Ref, storage::Segment::TrxRef, uint32_t col_len, char* error_msg, uint32_t error_msg_len); // DROP TABLE / ALTER TABLE DROP COLUMN. // Release any segments reserved in create(). Arena memory is freed by the // server after this call returns. bool drop(storage::Column::StorageCtx*, storage::Segment::TrxRef, char* error_msg, uint32_t error_msg_len); // Called when the server reattaches to existing storage (e.g. after restart). // Recover space and root_page from the StorageRef set in create(). bool load(storage::Column::StorageCtx*, storage::Column::StorageRef, char* error_msg, uint32_t error_msg_len); // INSERT. col_data is the encoded value; rowid_prefix identifies the owning // row. Write into your storage layout and return a Column::Ref the server // stores in the row payload in place of the value bytes. bool insert(storage::Column::StorageCtx*, storage::MtrCtx::Ref, storage::Segment::TrxRef, storage::Column::Data col_data, storage::Column::Data rowid_prefix, storage::Column::Ref* col_ref, char* error_msg, uint32_t error_msg_len); // SELECT. Given the Column::Ref produced by insert, populate col_data and // rowid_prefix, and report the writing transaction and delete-mark status. bool select(storage::Column::StorageCtx*, storage::MtrCtx::Ref, storage::Column::Ref, storage::Column::Data* col_data, storage::Column::Data* rowid_prefix, storage::Segment::TrxRef*, bool* delete_marked, char* error_msg, uint32_t error_msg_len); // DELETE (in-transaction). Set or clear the delete-mark flag. The actual // bytes must remain readable until purge() runs. bool mark_delete(storage::Column::StorageCtx*, storage::MtrCtx::Ref, storage::Segment::TrxRef, storage::Column::Ref, bool delete_mark, char* error_msg, uint32_t error_msg_len); // InnoDB purge. Reclaim storage for entries whose deleting transaction is // no longer visible to any active snapshot. bool purge(storage::Column::StorageCtx*, storage::MtrCtx::Ref, storage::Segment::TrxRef, storage::Column::Ref, char* error_msg, uint32_t error_msg_len); ``` `mark_delete` 및 `purge`는 InnoDB MVCC가 삭제된 행을 오래된 스냅샷에서 읽을 수 있도록 유지해야 하기 때문에 구분됩니다. ### 컬럼별 컨텍스트 및 아레나 C++ SDK는 `create` 또는 `load`를 호출하기 전에 `MyCtx`를 기본 생성합니다 — `ctx->user()`는 함수가 실행될 때 이미 채워져 있습니다. `MyCtx`는 기본 생성 가능해야 하며, C++ SDK는 인수 없이 `T()`를 호출합니다. `ctx->user()`를 직접 사용하여 상태를 초기화하세요. `ctx->arena().construct()`를 호출하지 마세요 — 이는 두 번째 사용되지 않는 인스턴스를 할당하고 `ctx->user()`가 이 인스턴스를 가리키지 않습니다. ```cpp theme={null} bool MyStorage::create(storage::Column::StorageCtx* ctx, storage::Space::Ref space, storage::Segment::TrxRef trx, uint32_t col_len, char* error_msg, uint32_t error_msg_len) { storage::Segment::PageRef root; if (storage::Segment::create(space, 1, trx, root) != storage::Error::SUCCESS) { snprintf(error_msg, error_msg_len, "%s", storage::last_error().data()); return true; } ctx->user()->space = space; ctx->user()->root_page = root; // Encode space and root into StorageRef so load() can recover both. ctx->set_ref((static_cast(space) << 32) | static_cast(root)); return false; } ``` `load`는 동일한 패턴을 따릅니다 — `ctx->user()`는 미리 채워져 있고, `storage_ref`는 `create`에서 `ctx->set_ref()`로 저장된 패킹된 값을 담고 있습니다: ```cpp theme={null} bool MyStorage::load(storage::Column::StorageCtx* ctx, storage::Column::StorageRef storage_ref, char* error_msg, uint32_t error_msg_len) { ctx->user()->space = static_cast(storage_ref >> 32); ctx->user()->root_page = static_cast(storage_ref & 0xFFFFFFFF); ctx->set_ref(storage_ref); return false; } ``` `ctx->arena()`는 `MyCtx`에 직접 포함할 수 없는 크기나 동적 객체를 할당하는 데만 사용하세요. C++ SDK는 `drop`이 반환된 후 자동으로 아레나를 파괴하고 `~MyCtx()`를 호출합니다(성공 여부와 무관). ### InnoDB 접근 유틸리티 InnoDB 원시 기능을 위해 ``를 포함합니다. 모든 페이지 읽기 및 쓰기는 미니 트랜잭션 내에서 발생해야 합니다: ```cpp theme={null} storage::MtrCtx mtr; storage::MtrCtx::Ref mtr_ref = mtr.start(); if (mtr_ref == nullptr) { /* OOM — handle error */ return true; } // ... page operations ... mtr.commit(); ``` 미니 트랜잭션 커밋은 페이지 락을 해제하고 변경 사항을 영구화하는 redo 로그 기록을 작성합니다. **세그먼트**는 `create` 시 예약됩니다 — 완전한 설정 패턴은 위 컬럼별 컨텍스트의 `create` 및 `load` 예제를 참조하세요. DML 작업 중에는 루트 페이지에서 세그먼트 참조를 얻어 새 페이지를 할당합니다: ```cpp theme={null} storage::Page root; root.load(ctx->user()->space, ctx->user()->root_page, storage::Page::Latch::EXCLUSIVE, mtr_ref); storage::Segment::Ref seg = storage::Segment::get_header(root, 0); storage::Page data_page; data_page.load_new(seg, mtr_ref); // allocates a fresh page ``` **페이지**는 공유 락으로 읽고 배타 락으로 쓰여야 합니다. InnoDB가 변경 사항을 로깅하도록 `mtr_ref`를 쓰기 호출에 전달합니다: ```cpp theme={null} storage::Page page; // Read page.load(ctx->user()->space, page_num, storage::Page::Latch::SHARED, mtr_ref); uint32_t v = page.read_integer_4(storage::Page::HEADER_SIZE + offset); // Write page.load(ctx->user()->space, page_num, storage::Page::Latch::EXCLUSIVE, mtr_ref); page.write_integer_4(storage::Page::HEADER_SIZE + offset, v, mtr_ref); ``` 페이지 레이아웃 상수: | 상수 | 값 | 참고 | | -------------------------------- | ------- | ---------------------------------------- | | `storage::Page::HEADER_SIZE` | `38` | 확장 데이터는 이 오프셋에서 시작됩니다. | | `storage::Page::TRAILER_SIZE` | `8` | `page_size - TRAILER_SIZE`를 초과하여 쓰지 마세요. | | `storage::Page::get_size(space)` | runtime | 16384을 하드코딩하는 대신 사용하세요. | 헤더 또는 트레일러 영역 내부에서 읽기 또는 쓰기 작업을 수행하면 페이지가 손상됩니다 — InnoDB는 해당 바이트 범위를 자체적인 관리 및 체크섬에 사용합니다. ## 문 이벤트 문 이벤트 기능(`vsql::preview::statement_event`)은 각 쿼리 실행이 완료된 후 확장 프로그램이 제공한 핸들러를 실행합니다. 서버는 쿼리 자체의 스레드에서 핸들러를 동기적으로 호출하고 실행 메타데이터 — 쿼리 텍스트, 타이밍, 행 개수, 연결 식별 정보, 그리고 옵티마이저 품질 지표를 전달합니다. 느린 쿼리 로깅, 감사 또는 메트릭 수집에 사용하세요. 기능 이름 `VEF_PREVIEW_STATEMENT_EVENT_NAME`은 `"vsql::preview::statement_event"`입니다. ### 기능 선언 파일 범위에서 발동 단계와 핸들러 함수로 인스턴스화된 `StatementEventCapability`을 선언하고 `.with()`에 전달합니다: ```cpp theme={null} #include #include namespace se = vsql::preview_statement_event; static void on_statement(const se::StatementEventArgs &args, se::StatementEventResult &result) { // inspect args; optionally write an advisory message via result } static se::StatementEventCapability g_statement_event; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_statement_event)) ``` 첫 번째 템플릿 인수는 발동 단계이며, `vef_statement_event_phase_t` 값입니다. `VEF_STATEMENT_EVENT_POSTEXECUTE`는 쿼리 실행이 완료된 후 성공 또는 실패와 관계없이 발동하며, 이 버전에서 구현된 유일한 단계입니다. 다른 `vef_statement_event_phase_t` 값은 예약되어 있으며, 그중 하나에 대한 핸들러를 선언하면 서버가 `INSTALL EXTENSION`을 거부합니다. ### 핸들러 인수 `StatementEventArgs`는 완료된 쿼리의 읽기 전용 뷰입니다. POSTEXECUTE 단계에서는 모든 필드가 채워져 있습니다. 주요 접근자: | 접근자 | 의미 | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `query()` | 쿼리 텍스트, `string_view`로. 서버가 문의 재작성된 형태를 가지고 있는 경우, 이것이 그 형태입니다 — 일반 로그, 슬로우 쿼리 로그, 바이너리 로그가 기록하는 것과 동일한, 민감 정보가 가려진(마스킹된) 텍스트입니다. | | `query_time_secs()` | 실제 실행 시간, 초 단위. | | `lock_time_secs()` | 락을 기다리는 데 소요된 시간, 초 단위. | | `rows_sent()`, `rows_examined()`, `rows_affected()` | 행 카운터. | | `user()`, `client_ip()`, `connection_id()` | 연결 식별 정보. | | `schema()` | 기본 스키마, 또는 선택된 것이 없으면 `NULL`. | | `status()` | 성공 시 `0`, 그렇지 않으면 MySQL 오류 코드. | | `digest_text()` | 유사한 쿼리를 그룹화하기 위한 정규화된 쿼리 형태. | | `no_index_used()` | 쿼리가 사용 가능한 인덱스 없이 실행되었을 때 `true`. | `query()`는 재작성된 형태가 존재하는 경우 그것을 반환하므로, 자격 증명을 담은 문은 일반 로그, 슬로우 쿼리 로그, 바이너리 로그가 이미 민감 정보를 가리는 방식과 일치하게 비밀이 평문이 아닌 난독화된 상태로 도착합니다: `SET PASSWORD`, `CREATE`/`ALTER USER ... IDENTIFIED BY`, `CHANGE REPLICATION SOURCE ... SOURCE_PASSWORD`, 그리고 `CREATE SERVER ... OPTIONS(PASSWORD ...)`. 재작성 규칙이 없는 문은 그대로 전달됩니다. `query()`, `sqlstate()`, `error_message()`와 같은 문자열 접근자는 핸들러 호출 기간 동안만 유효한 저장소를 가리킵니다 — 핸들러가 반환된 후에도 필요하면 바이트를 복사하세요. `StatementEventResult::error_msg(fmt, ...)`은 printf 형식의 메시지를 작성합니다. POSTEXECUTE 단계에서는 이 메시지가 권고용입니다: 서버가 로깅하지만 클라이언트에 전파하지 않습니다. ### 완전한 예제 서버와 함께 제공되는 [`vsql_slow_query_log`](https://github.com/villagesql/villagesql-server/tree/main/villagesql/test-extensions/vsql-slow-query-log) 테스트 확장 프로그램의 축약된 형태입니다. 이는 실행 시간이 임계값을 초과하는 각 쿼리를 로깅하며, 문 이벤트 기능을 런타임 구성을 위한 [시스템 변수](#system-variables)와 결합합니다: ```cpp theme={null} #include #include #include #include #include #include #include #include using namespace vsql; namespace sv = vsql::preview_sys_var; namespace se = vsql::preview_statement_event; static bool g_enabled; static long long g_threshold_ms; static char *g_log_filename; static std::mutex g_log_mutex; static void slow_query_hook(const se::StatementEventArgs &args, se::StatementEventResult &result) { if (!g_enabled) return; if (args.query_time_secs() * 1000.0 < static_cast(g_threshold_ms)) return; time_t now = static_cast(args.query_start_utime() / 1000000); char ts[32]; struct tm tm_utc; gmtime_r(&now, &tm_utc); strftime(ts, sizeof(ts), "%Y-%m-%dT%H:%M:%SZ", &tm_utc); std::lock_guard lock(g_log_mutex); FILE *f = fopen(g_log_filename, "a"); if (f == nullptr) { result.error_msg("failed to open '%s': %s", g_log_filename, strerror(errno)); return; } fprintf(f, "# Time: %s\n", ts); fprintf(f, "# User@Host: %s @ %s Id: %lu\n", args.user() ? args.user() : "", args.client_ip() ? args.client_ip() : "", args.connection_id()); fprintf(f, "# Schema: %s Query_time: %.6f Lock_time: %.6f" " Rows_sent: %llu Rows_examined: %llu\n", args.schema() ? args.schema() : "", args.query_time_secs(), args.lock_time_secs(), (unsigned long long)args.rows_sent(), (unsigned long long)args.rows_examined()); fprintf(f, "SET timestamp=%llu;\n", (unsigned long long)now); auto q = args.query(); fprintf(f, "%.*s;\n", (int)q.size(), q.data()); fclose(f); } static auto SYS_VARS = sv::make_capability({ sv::make_bool("enabled", "Enable the slow query log", &g_enabled, false), sv::make_int("threshold_ms", "Minimum execution time to log, in ms", &g_threshold_ms, 1000, 0, 3600000), sv::make_str("log_file", "Path to the slow query log file", &g_log_filename, "/tmp/vsql_slow_query.log")}); static se::StatementEventCapability STATEMENT_EVENT; VEF_GENERATE_ENTRY_POINTS( make_extension().with(SYS_VARS).with(STATEMENT_EVENT)) ``` #### SQL에서 활성화 미리보기 계층이 활성화된 상태에서(참조: [미리보기 계층 활성화](#enabling-the-preview-tier)), 확장 프로그램을 설치하고 시스템 변수를 통해 구성합니다: ```sql theme={null} INSTALL EXTENSION vsql_slow_query_log; SET GLOBAL vsql_slow_query_log.enabled = ON; SET GLOBAL vsql_slow_query_log.threshold_ms = 500; ``` 임계값보다 느린 각 쿼리는 구성된 로그 파일에 추가됩니다: ``` # Time: 2026-06-22T22:53:44Z # User@Host: root @ Id: 27 # Schema: Query_time: 0.605084 Lock_time: 0.000000 Rows_sent: 1 Rows_examined: 1 SET timestamp=1782168824; SELECT SLEEP(0.6); ```