메인 콘텐츠로 건너뛰기

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
VillageSQL 확장은 서버가 런타임에 로드하는 공유 라이브러리입니다. VEF SDK는 타입이 지정된 C++ 래퍼를 제공하므로 원시 FFI를 건드리지 않고 확장 함수를 작성할 수 있습니다. 이 가이드는 최소한의 확장을 처음부터 빌드하는 과정을 안내합니다.

C++를 선택해야 하는 경우

다음과 같은 경우 C++가 올바른 선택입니다:
  • 팀에 이미 C++ 코드베이스가 있고 확장을 같은 언어로 유지하고 싶을 때
  • 정밀한 바이너리 레이아웃을 가진 사용자 정의 유형이 필요할 때(C++ 유형 빌더가 가장 완전한 API입니다)
  • SQL 함수로 노출하고 싶은 기존 C++ 라이브러리를 다루고 있을 때
Rust를 선호하고 C++ 요구 사항이 없다면 Rust 확장 작성하기를 참조하세요.

사전 요구 사항

확장 코드를 작성하기 전에 VillageSQL 빌드가 필요합니다 — 확장은 서버의 SDK 헤더와 빌드 트리에 링크됩니다. 다음도 필요합니다:
  • C++17 컴파일러 — GCC 8+, Clang 8+, 또는 MSVC 2019+
  • CMake 3.18+ — 확장 템플릿은 CMake를 사용합니다
아직 서버를 빌드하지 않았다면 먼저 소스에서 빌드 가이드를 따르세요.

CMake 설정

가장 빠르게 시작하는 방법은 vsql-extension-template을 사용하는 것입니다. 포크하거나 복제하세요:
템플릿의 CMakeLists.txt가 VEF 빌드 설정을 대신 처리합니다 — CMake를 처음부터 작성하기보다 템플릿을 복사하여 수정하세요. -DVillageSQL_BUILD_DIR로 빌드 디렉토리를 구성합니다:
-DVillageSQL_BUILD_DIR은 CMake에 VillageSQL 빌드가 어디 있는지 알려 주어 SDK 헤더를 찾을 수 있게 합니다. 이렇게 하면 빌드 출력에 .veb 파일이 생성됩니다. 전체 CMake 설정은 확장 만들기와 vsql-extension-template을 참조하세요.

C++로 작성한 최소 VDF

VEF SDK 헤더를 포함하고 빌더 API를 사용하여 함수를 등록합니다. 다음은 문자열 반전 함수를 구현하는 완전한 확장입니다:
주목할 점 몇 가지:
  • <villagesql/extension.h>(이전 V1 헤더)가 아니라 <villagesql/vsql.h>를 포함하세요
  • 타입이 지정된 인수 래퍼(StringArg, IntArg, RealArg)는 null을 확인하고 타입이 지정된 값을 노출합니다 — 원시 포인터 연산이 없습니다
  • out.set_null(), out.warning(msg), out.error(msg)가 성공이 아닌 세 가지 반환입니다
  • VEF_GENERATE_ENTRY_POINTS는 원시 구조체가 아니라 make_extension() 빌더를 받습니다
정수나 실수를 반환하는 함수의 경우:
함수를 결정적(같은 입력은 항상 같은 출력을 생성)으로 선언하려면 빌더 체인에 .deterministic()을 추가하세요:
결정적 함수는 생성 열과 함수 인덱스에서 사용할 수 있습니다. 실제로 결정적일 때만 .deterministic()을 추가하세요.

빌드

위의 CMake 설정 절에서 cmake 구성 단계를 마친 후 빌드하고 설치합니다:
make install은 .veb 파일을 VillageSQL 확장 디렉토리로 복사합니다.

설치 및 테스트

VillageSQL에 연결하여 확장을 설치합니다:
로드되었는지 확인합니다:
함수를 호출합니다:
자동화된 테스트를 위해 mysql-test/t/에 MySQL Test Framework 스위트를 작성합니다:
예상 결과를 생성하고 실행합니다:

함께 보기