vsql_allow_preview_extensions = ON이 필요합니다. 미리보기 계층을 활성화하고 기능을 등록하는 방법은 미리보기 기능을 참조하세요.
상태 변수
status_var 기능(vsql::status_var)은 확장 프로그램이 MySQL 상태 변수로 long long 및 double 카운터를 노출할 수 있게 해줍니다. 확장 프로그램은 저장소를 소유하고 쓰며, 서버는 상태 변수가 쿼리될 때마다 포인터를 통해 읽습니다.
vsql::preview_status_var::make_capability()으로 기능을 구축하고, make_int(name, value_ptr) 또는 make_double(name, value_ptr)에서 제공하는 디스크립터 목록을 중괄호로 감싸 전달합니다. 템플릿은 중괄호 목록에서 개수를 추론하므로 명시적 크기는 필요하지 않습니다.
완전한 예제
make_int는 long long *를 요구하며, make_double는 double *를 요구합니다. 이 두 유형만 지원됩니다.
SQL에서 접근
INSTALL EXTENSION my_ext 후, 변수는 확장 프로그램 이름을 접두사로 사용하여 사용 가능합니다:
++를 사용해 동시 증가가 때로 손실될 수 있지만, 이는 SHOW STATUS를 통해 노출된 근사 호출 카운터에 대해 허용됩니다.
시스템 변수
sys_var 기능(vsql::sys_var)은 확장 프로그램이 소유한 저장소를 기반으로 하는 MySQL 시스템 변수를 등록할 수 있게 해줍니다. 네 가지 유형이 지원됩니다: BOOL(bool *), INT(long long *), STR(char **), 그리고 ENUM(unsigned long *, 고정된 순서의 이름 목록에 대한 0 기반 인덱스를 저장). INT 디스크립터는 min_val 및 max_val 경계도 포함하며, 모든 디스크립터는 기본값과 주석을 포함합니다.
vsql::preview_sys_var::make_capability()으로 기능을 구축하고, 대응하는 팩토리 함수인 make_bool, make_int, make_str, 그리고 make_enum을 사용합니다. 기능 객체는 확장 코드에서의 프로그래밍 접근을 위해 get() 및 set()을 노출합니다. 둘 다 성공 시 false를 반환합니다.
값 변경에 반응하려면 디스크립터에 .on_change<&fn>()을 연결합니다. 콜백은 var_name() 및 타입 접근자(as_int(), as_str(), 그리고 as_enum())를 포함하는 sv::SysVarChange를 수신합니다.
서버는 전역 시스템 변수 잠금을 보유한 상태에서 그 콜백을 호출합니다. 그곳에서 이 확장 프로그램의 다른 변수를 저장소 포인터를 통해 읽거나 쓰는 것은 안전하며, 서버가 동일한 잠금 아래에서 그 변수들을 읽기 때문에 다른 세션은 새 값을 즉시 봅니다.
기능 객체는 정적 저장 기간을 가져야 합니다. MySQL은 사용자가 변수를 설정할 때 저장소 포인터에 직접 씁니다.
열거형 변수는 이름(
SET GLOBAL my_ext.mode = 'sync')으로 또는 이름의 0 기반 인덱스로 설정합니다. 어느 쪽이든 서버는 값을 수락하기 전에 names와 대조하여 검증하며, 인식되지 않는 이름이나 범위를 벗어난 인덱스는 저장하는 대신 거부합니다:
make_str과 구별되는 점입니다: 값 공간이 닫혀 있고 SET 시점에 강제됩니다. 편의 오버로드는 static const char *const NAMES[] = {...} 배열에서 name_count를 추론하므로, 개수 인수를 생략할 수 있습니다.
완전한 예제
SQL에서 접근
INSTALL EXTENSION my_ext 후, 변수는 확장 프로그램 이름을 구성 접두사로 사용하여 접근 가능합니다:
확장 코드에서 읽기 및 쓰기
INT 및 BOOL 변수의 경우, 전역 저장소 포인터를 직접 읽습니다 — MySQL은 이들을 원자적으로 업데이트합니다. MySQL을 통해 변수를 업데이트하려면(잠금, 범위 검증, 지속성이 서버에서 처리되도록),SYS_VARS.set(extension_name, var_name, scope, value)를 호출합니다. set 및 get 둘 다 성공 시 false를 반환합니다. 둘 중 어느 것도 on_change 콜백에서 호출할 수 없습니다: 둘 다 시스템 변수 잠금에서 교착 상태가 발생합니다.
set과 get은 확장 프로그램 이름과 변수 이름을 const char *로 받습니다. INT 변수는 정수 값으로만 설정됩니다. 문자열 값으로 set을 호출하면 실패하고 true를 반환합니다(INT 변수의 경우). BOOL, STRING, DOUBLE, ENUM 변수는 문자열 값으로 설정하세요.
scope 인수는 다음과 같이 지속성을 제어합니다:
세션 변수
session_var 기능(vsql::session_var)은 확장 프로그램이 세션별(THD 로컬) 시스템 변수를 등록할 수 있게 해줍니다 — 플러그인의 MYSQL_THDVAR_*에 기능적으로 상응하는 것입니다. 이는 vsql::sys_var의 세션 범위 형제입니다: sys_var는 모든 연결이 공유하는 하나의 값을 갖는 반면, session_var는 각 연결에 SET SESSION으로 설정하는 자체 값을 부여합니다. 새 세션의 시작점은 디스크립터의 기본값 또는 SET GLOBAL로 마지막으로 저장된 값입니다. 변수의 범위는 등록 시 고정됩니다 — 세션별 변수에는 이 기능을, 전역 변수에는 vsql::sys_var를 사용하세요.
두 가지 유형만 지원됩니다: INT(long long)와 STR(std::string). BOOL 또는 DOUBLE 세션 변수는 없으며, on_change 콜백 메커니즘도 없습니다 — vsql::sys_var와 달리, 확장 프로그램은 세션 변수의 값을 변경 시 알림을 받는 것이 아니라 다시 읽어서만 관찰합니다.
기능 선언
vsql::preview_session_var::make_capability()으로 기능을 구축하고, make_int(name, comment) 또는 make_str(name, comment)에서 제공하는 디스크립터 목록을 중괄호로 감싸 전달합니다. 각 디스크립터는 플루언트 .default_(), .min(), .max() 설정자로 구성합니다(min/max는 INT에만 적용됩니다):
make_int는 제약 없이 시작합니다(기본값 0, 전체 long long 범위). make_str은 빈 문자열 기본값으로 시작합니다. 기능 객체는 이 페이지의 다른 모든 미리보기 기능과 마찬가지로 정적 저장 기간이 필요합니다.
세션 값 읽기
두 가지 읽기 경로가 있으며, 둘 다 호출하는 연결의 스레드에 대해 해석됩니다 — 따라서 둘 다 연결 스레드(연결에서 실행되는 VDF 또는 콜백)에서 호출해야 하며, 백그라운드 스레드 워커에서는 절대 호출하면 안 됩니다:SESSION_VARS.get_session_int(name, out)/get_session_str(name, out)— 이름 기반이며, 호출마다 변수를 다시 해석합니다. 가끔 읽는 경우에 사용하세요.STR변수의 경우 이것이 유일한 경로입니다: 잠금 없는 문자열 빠른 경로는 없는데,STR슬롯은 별도로 할당된 버퍼에 대한 포인터를 보유하며 동시에 실행되는SET SESSION또는UNINSTALL이 그 버퍼를 해제할 수 있기 때문입니다.SESSION_VARS.int_var(name)은 첫read()시 지연 해석하고 결과를 캐시하는IntVar를 반환하므로, 기능이 로드되기 전에 파일/정적 범위에서 선언할 수 있습니다. 이후의 각read()는 잠금 없는 스레드별 오프셋 로드입니다 — 이름 조회 없음, 전역 잠금 없음 — 플러그인의THDVAR(thd, var)에 상응합니다. 이 빠른 경로는INT전용입니다.
SQL에서 접근
INSTALL EXTENSION my_ext 후, 각 변수는 확장 프로그램 이름을 구성 접두사로 사용하며 @@session.과 @@global. 둘 다로 읽고 설정할 수 있습니다:
SET SESSION에 영향을 받지 않으며, 자체 값을 설정하기 전까지는 컴파일된 기본값을 봅니다. SET GLOBAL은 새 세션이나 재설정된 세션이 가져오는 기본값을 변경하며, 이미 설정된 어떤 세션의 값도 변경하지 않습니다.
범위를 벗어난 INT 대입은 경계값으로 잘리고 경고가 발생하며, 잘못된 유형의 대입은 거부됩니다. 일반 MySQL 시스템 변수와 정확히 동일합니다:
재시작 동작
SET PERSIST와 SET PERSIST_ONLY는 다른 MySQL 시스템 변수와 마찬가지로 세션 변수의 전역 값에 대해 작동합니다: 값은 서버 재시작 후에도 유지되고, 각 새 세션은 그 값에서 시작합니다. SET SESSION 값은 연결별 상태이며 재시작 후 유지되지 않습니다. SET PERSIST가 없으면, 확장 프로그램이 여전히 설치된 상태로 재시작한 후 각 변수는 컴파일된 기본값으로 다시 나타납니다.