vsql_allow_preview_extensions = ON이 필요합니다. 미리보기 계층을 활성화하고 기능을 등록하는 방법은 미리보기 기능을 참조하세요.
Keyring 접근
keyring 기능(vsql::preview::keyring)은 MySQL keyring 구성 요소에 저장된 비밀을 읽고 쓸 수 있게 해줍니다. 확장 프로그램은 API 키, 암호화 키 또는 SQL 테이블에 저장되지 않아야 하는 기타 비밀을 처리하는 데 사용합니다.
기능 이름 VEF_PREVIEW_KEYRING_NAME은 "vsql::preview::keyring"입니다.
keyring 구성 요소(예: component_keyring_file)는 Keyring 구성 요소 설치에 설명된 대로 구성 요소 매니페스트와 그 구성 파일을 통해 서버 시작 시 로드되어야 합니다. INSTALL COMPONENT로는 사용할 수 없습니다. 없으면 작업은 KeyringCapability::Status::UNAVAILABLE을 반환합니다.
상태 값
KeyringCapability::Status는 read()(내부 ReadResult에서) 및 write()에서 반환되는 범위화된 열거형입니다:
기능 선언
헤더를 포함하고 파일 범위에서 기능 객체를 선언한 후.with()에 전달합니다:
g_keyring 객체는 서버가 로드 시 채웁니다. keyring 구성 요소가 설치되지 않은 경우 read() 및 write() 메서드는 런타임에 Status::UNAVAILABLE을 반환합니다 — 별도의 가용성 검사 대신 각 호출에서 상태를 확인하세요.
읽기 및 쓰기
data_id는 키 식별자입니다. auth_id는 소유 사용자입니다 — 내부 키(특정 사용자와 연결되지 않음)를 읽거나 쓰려면 빈 문자열(또는 read에서 생략, 기본값 {})을 전달합니다.
read는 값으로 ReadResult를 반환합니다. 구조화된 바인딩으로 바인딩합니다:
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.
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 자체 헤더를 포함하세요 — 해당 헤더가 서비스의 유형과 메서드를 선언하는 곳입니다:
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 리더를 요청합니다:
MySQL 헤더에 대해 빌드
서비스 정의는 VEF가 아니라 MySQL의 구성 요소 프레임워크에 속하며, 서버는 이를 설치하지 않습니다. 따라서mysql/components/services/*.h는 확장 프로그램 SDK에도, make install이 빌드하는 어떤 것에도 없으며, 여기에는 릴리스 tarball과 Docker 이미지가 포함됩니다. 서비스를 사용하는 확장 프로그램은 VillageSQL 서버 소스 트리에 대해 빌드합니다:
인트리 테스트 확장 프로그램은
vsql_add_test_extension()의 MYSQL_HEADERS 플래그에서 둘 다 얻으며, 이 플래그는 이들을 MYSQL_INCLUDE_DIR 및 MYSQL_GENERATED_INCLUDE_DIR로 전달합니다. 아웃오브트리 빌드는 자체 포함 경로를 설정합니다.
두 가지 빌드 실패는 원인이 된 줄이 아닌 다른 곳에서 나타납니다.
서비스의 MySQL 헤더를 생략하면 VSQL_REQUIRE_SERVICE에 아무것도 해석되지 않는 이름이 남으므로, 오류는 누락된 include가 아니라 매크로에서 나타납니다(clang 17):
<cstddef>를 포함하지 않고 size_t를 사용하므로, 그러한 헤더 중 하나를 모든 villagesql 헤더보다 앞에 두면 MySQL 자체 헤더 내부에서 실패합니다:
<cstddef>를 먼저 포함하세요.
서비스 호출
서비스 참조는 자체적으로valid()를 노출하며, ->는 서비스로 전달됩니다. 참조에는 .를, 서비스에는 ->를 사용하세요:
-> 호출 전에 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는 레지스트리에 없는 서비스를 요구하는 인트리 테스트 확장 프로그램입니다. 설치할 수 있는 것이 아니라 — 이 실패를 포착한 방법이며, 이 서버가 제공하지 않는 서비스를 요구할 때 여러분의 확장 프로그램이 생성하는 결과입니다:
MysqlServices 객체를 .with()에서 빠뜨리는 경우, 그리고 vsql_allow_preview_extensions가 OFF인 서버에 설치하는 경우입니다. 둘 다 등록 패턴에서 다룹니다.
완전한 예제
서버의villagesql/test-extensions/ 트리에 있는 vsql_mysql_services_session_test의 간단한 버전입니다. 이는 두 서비스를 조합하여 호출 세션에서 실행 중인 SQL 명령을 읽습니다: 하나는 현재 THD를 반환하고, 다른 하나는 그 위에서 이름이 지정된 속성을 읽습니다. 둘 다 모든 서버에 등록되는 서버 코어 서비스이므로, 먼저 설치할 것이 없습니다: