C++ 확장 예제

vsql_complex 확장은 VillageSQL의 C++ SDK를 사용한 사용자 정의 유형에 대한 참조 구현체로, 실제 운영 환경에서 사용할 수 있는 확장 패턴을 보여줍니다. 소스: VillageSQL 저장소의 villagesql/examples/vsql-complex/

vsql_complex가 제공하는 기능

복소수(a + bi)를 위한 COMPLEX 유형으로 산술, 유틸리티 및 집계 기능을 제공합니다. 사용 예시:

INSTALL EXTENSION vsql_complex;

CREATE TABLE signals (
    id INT PRIMARY KEY,
    impedance COMPLEX
);

INSERT INTO signals VALUES (1, '(50.0,10.0)');

SELECT
    complex_real(impedance) as resistance,
    complex_imag(impedance) as reactance,
    complex_abs(impedance) as magnitude
FROM signals;

디렉토리 구조

vsql_complex/
├── CMakeLists.txt       # Build config with VEF_CREATE_VEB
├── manifest.json        # Extension metadata
├── src/
│   └── complex.cc       # Complete implementation: types, functions, and VEF registration
└── test/
    ├── t/*.test         # Test cases
    └── r/*.result       # Expected results

VEF 등록 패턴

파일: src/complex.cc vsql_complex는 C++ SDK의 VEF_GENERATE_ENTRY_POINTS() 매크로를 사용합니다:

#include <villagesql/vsql.h>

// Type name constants as char arrays — required as non-type template parameters
// (NTTPs) so that make_type can auto-generate VDF names like "COMPLEX::from_string".
static constexpr const char kComplexTypeName[] = "COMPLEX";
static constexpr const char kComplex2TypeName[] = "COMPLEX2";

// Type objects: encode/decode/compare VDFs are embedded via template parameters.
// No separate .func() registration is needed for type operations.
constexpr auto COMPLEX =
    vsql::make_type<kComplexTypeName>()
        .persisted_length(kComplexSize)
        .max_decode_buffer_length(64)
        .from_string<&complex_from_string>()
        .to_string<&complex_to_string>()
        .compare<&complex_compare>()
        .intrinsic_default_str("(0,0)")
        .build();

constexpr auto COMPLEX2 =
    vsql::make_type<kComplex2TypeName>()
        .persisted_length(kComplexSize)
        .max_decode_buffer_length(64)
        .from_string<&complex2_from_string>()
        .to_string<&complex_to_string>()
        .compare<&complex_compare>()
        .hash<&complex2_hash>()
        .intrinsic_default_str("(0,0)")
        .build();

using namespace vsql;

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .type(COMPLEX)
        .type(COMPLEX2)
        // Arithmetic operations
        .func(make_func<&complex_add>("complex_add")
                  .returns(COMPLEX)
                  .param(COMPLEX)
                  .param(COMPLEX)
                  .deterministic()
                  .build())
        .func(make_func<&complex_subtract>("complex_subtract")
                  .returns(COMPLEX)
                  .param(COMPLEX)
                  .param(COMPLEX)
                  .deterministic()
                  .build())
        .func(make_func<&complex_multiply>("complex_multiply")
                  .returns(COMPLEX)
                  .param(COMPLEX)
                  .param(COMPLEX)
                  .deterministic()
                  .build())
        .func(make_func<&complex_divide>("complex_divide")
                  .returns(COMPLEX)
                  .param(COMPLEX)
                  .param(COMPLEX)
                  .deterministic()
                  .build())
        // Utility functions
        .func(make_func<&complex_real>("complex_real")
                  .returns(REAL)
                  .param(COMPLEX)
                  .deterministic()
                  .build())
        .func(make_func<&complex_imag>("complex_imag")
                  .returns(REAL)
                  .param(COMPLEX)
                  .deterministic()
                  .build())
        .func(make_func<&complex_abs>("complex_abs")
                  .returns(REAL)
                  .param(COMPLEX)
                  .deterministic()
                  .build())
        .func(make_func<&complex_conjugate>("complex_conjugate")
                  .returns(COMPLEX)
                  .param(COMPLEX)
                  .deterministic()
                  .build())
        // Aggregate functions
        .func(make_aggregate_func<ComplexSumState, &complex_sum_result>(
                  "complex_sum")
                  .returns(COMPLEX)
                  .param(COMPLEX)
                  .clear<&complex_sum_clear>()
                  .accumulate<&complex_sum_accumulate>()
                  .build()))

핵심 패턴:

단일 매크로 호출로 모든 것을 등록 — 수동 SQL 필요 없음
유형 객체는 vsql::make_type<kName>()로 빌드된 constexpr 변수이며, kName은 비유형 템플릿 매개변수로 사용되는 static constexpr const char[]임
유형 연산(.from_string<>(), .to_string<>(), .compare<>(), .hash<>())은 유형 객체 내에 내장되어 있으며 별도의 .func() 호출이 필요하지 않음
.compare()는 ORDER BY 및 인덱싱을 가능하게 함; .hash()는 선택적임
.intrinsic_default_str("(0,0)")은 INSERT IGNORE 또는 UPDATE IGNORE가 이 유형의 NOT NULL 열에 NULL을 할당할 때 기록되는 기본값을 설정함
함수 등록은 make_func<&impl>("name")과 .build()를 사용함
집계 등록은 make_aggregate_func<State, &result_fn>("name")과 .clear<&fn>() 및 .accumulate<&fn>()을 사용하며, 결과 함수는 void(const State&, ResultType) 서명을 가짐

이진 저장 형식

COMPLEX는 16바이트(리틀엔디안)로 저장됩니다:

바이트 0-7: 실수 부분(double)
바이트 8-15: 허수 부분(double)

인코딩/디코딩 (complex.cc):

void complex_from_string(std::string_view from, vsql::CustomResult out);
void complex_to_string(vsql::CustomArg in, vsql::StringResult out);

플랫폼 독립적인 바이트 순서 함수를 사용하여 크로스 플랫폼 호환성을 보장합니다.

인수 및 결과 유형

구현 코드에서는 원시 프로토콜 구조체 대신 타입화된 인수 및 결과 유형을 사용합니다: 산술 예시 (complex.cc에서):

void complex_add(CustomArg in_l, CustomArg in_r, CustomResult out) {
  // Handle NULL inputs and validate arguments
  // ...
  store_complex(out.buffer().data(), Complex{lhs.re + rhs.re, lhs.im + rhs.im});
  out.set_length(kComplexSize);
}

유틸리티 함수 (complex.cc에서):

void complex_real(CustomArg in, RealResult out) {
  // Handle NULL and validate
  // ...
  out.set(cx.re);
}

void complex_abs(CustomArg in, RealResult out) {
  // Handle NULL and validate
  // ...
  out.set(sqrt(cx.re * cx.re + cx.im * cx.im));
}

테스트 전략

테스트 파일 (test/t/complex_create.test):

INSTALL EXTENSION vsql_complex;

CREATE TABLE test_create_basic (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(50),
    complex_val COMPLEX
);

INSERT INTO test_create_basic (name, complex_val) VALUES ('test1', '(1,2)');
INSERT INTO test_create_basic (name, complex_val) VALUES ('scientific', '(1.5e-10,2.3e+15)');

SELECT id, name, complex_val FROM test_create_basic ORDER BY id;

DROP TABLE test_create_basic;
UNINSTALL EXTENSION vsql_complex;

결과 생성:

cd /path/to/villagesql/build/mysql-test
./mysql-test-run.pl --suite=villagesql/examples/vsql-complex --record

테스트 실행:

./mysql-test-run.pl --suite=villagesql/examples/vsql-complex

핵심 구현 패턴

패턴	사용법
고정 길이 저장	유형 빌더에서 `.persisted_length()` 설정
플랫폼 독립적	double에 대한 사용자 정의 바이트 순서 함수 사용
NULL 처리	인수 유형에서 `in.is_null()` 호출
오류 처리	결과 유형에서 `out.error("message")` 호출
결과 출력	결과 유형에서 `out.set(value)` / `out.set_length(n)` 호출

매니페스트

파일: manifest.json

{
  "name": "vsql_complex",
  "version": "0.0.1",
  "description": "Complex number type for VillageSQL",
  "author": "VillageSQL Community",
  "license": "GPL-2.0"
}

사용자 정의 유형을 포함한 데이터 내보내기 및 가져오기

VillageSQL은 사용자 정의 유형에 대해 SELECT INTO OUTFILE 및 LOAD DATA INFILE을 지원하여 사용자 정의 유형 값을 유지한 채 데이터를 내보내고 가져올 수 있습니다. 두 문 모두 secure_file_priv가 쓰기 가능한 디렉터리를 지정하거나 비어 있어야 합니다. 기본값인 secure_file_priv=NULL 상태로 둔 서버는 이러한 문을 ERROR 1290과 함께 즉시 거부합니다.

SELECT INTO OUTFILE

사용자 정의 유형은 내보낼 때 문자열 표현으로 직렬화됩니다:

INSTALL EXTENSION vsql_complex;

-- Create table with custom type
CREATE TABLE signals (
    id INT PRIMARY KEY,
    reading COMPLEX
);

INSERT INTO signals VALUES
    (1, '(3.0,4.0)'),
    (2, '(5.0,12.0)'),
    (3, '(-1.0,2.0)');

-- Export to file
SELECT * FROM signals INTO OUTFILE '/tmp/signals_export.txt';

파일 내용 (/tmp/signals_export.txt):

(3,4)
(5,12)
(-1,2)

LOAD DATA INFILE

내보낸 데이터를 테이블로 다시 로드합니다:

-- Create new table with same schema
CREATE TABLE signals_imported (
    id INT PRIMARY KEY,
    reading COMPLEX
);

-- Import data
LOAD DATA INFILE '/tmp/signals_export.txt' INTO TABLE signals_imported;

-- Verify
SELECT * FROM signals_imported;

사용자 정의 구분자로 내보내기

사용자 정의 필드 및 줄 종결자 사용 가능:

SELECT * FROM signals
INTO OUTFILE '/tmp/signals_csv.txt'
FIELDS TERMINATED BY ','
ENCLOSED BY '"'
LINES TERMINATED BY '\n';

출력:

"1","(3,4)"
"2","(5,12)"
"3","(-1,2)"

VDF 함수로 내보내기

확장 함수를 사용하여 계산된 값을 내보냅니다:

SELECT
    id,
    reading,
    complex_abs(reading) AS magnitude,
    complex_real(reading) AS real_part,
    complex_imag(reading) AS imag_part
INTO OUTFILE '/tmp/signals_computed.txt'
FROM signals;

사용자 정의 유형은 SELECT ... INTO OUTFILE에 의해 문자열 표현으로 내보내지고 LOAD DATA INFILE에 의해 다시 읽힙니다. SELECT ... INTO DUMPFILE은 문자열 표현을 쓰지 않습니다: 그 방식으로 쓴 COMPLEX 값은 (3,4)가 아니라 16개의 이진 바이트로 기록됩니다.

다음 단계

확장 생성

자체 확장 구축

확장 아키텍처

내부 구조 이해

vsql_complex 소스

완전한 소스 코드 보기

사용 가능한 확장

확장 카탈로그 탐색

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

vsql_complex가 제공하는 기능

디렉토리 구조

VEF 등록 패턴

이진 저장 형식

인수 및 결과 유형

테스트 전략

핵심 구현 패턴

매니페스트

사용자 정의 유형을 포함한 데이터 내보내기 및 가져오기

SELECT INTO OUTFILE

LOAD DATA INFILE

사용자 정의 구분자로 내보내기

VDF 함수로 내보내기

다음 단계

확장 생성

확장 아키텍처

vsql_complex 소스

사용 가능한 확장

​vsql_complex가 제공하는 기능

​디렉토리 구조

​VEF 등록 패턴

​이진 저장 형식

​인수 및 결과 유형

​테스트 전략

​핵심 구현 패턴

​매니페스트

​사용자 정의 유형을 포함한 데이터 내보내기 및 가져오기

​SELECT INTO OUTFILE

​LOAD DATA INFILE

​사용자 정의 구분자로 내보내기

​VDF 함수로 내보내기

​다음 단계

확장 생성

확장 아키텍처

vsql_complex 소스

사용 가능한 확장

vsql_complex가 제공하는 기능

디렉토리 구조

VEF 등록 패턴

이진 저장 형식

인수 및 결과 유형

테스트 전략

핵심 구현 패턴

매니페스트

사용자 정의 유형을 포함한 데이터 내보내기 및 가져오기

SELECT INTO OUTFILE

LOAD DATA INFILE

사용자 정의 구분자로 내보내기

VDF 함수로 내보내기

다음 단계