// ... read src, write result to dst ...
out.set_length(src.size());
}
```
`.param(COMPLEX)` 및 `.returns(COMPLEX)`로 등록:
```cpp theme={null}
.func(make_func<&complex_conjugate_impl>("complex_conjugate")
.returns(COMPLEX)
.param(COMPLEX)
.build())
```
자세한 `CustomArg`/`CustomResult` API(파라미터화된 유형을 위한 `CustomArgWith` 및 `CustomResultWith
`)는 [개발 가이드](/docs/ko/mysql-8.4/0.0.4/development#typed-wrappers-recommended)를 참조하세요.
### 결정적 함수
기본적으로 VDF는 비결정적으로 등록됩니다. 비결정적 함수는 생성된 열, CHECK 제약 조건, 표현식 기본값(`DEFAULT (expr)` 열) 세 가지 SQL 컨텍스트에서 차단됩니다. 비결정적 VDF를 이러한 기능과 함께 사용하면 오류가 반환됩니다. 함수가 동일한 입력에 항상 동일한 출력을 생성하고 부작용이 없으면 빌더 체인에 `.deterministic()`을 추가하여 결정적이라고 선언할 수 있습니다.
최적화기는 이 정보를 사용하여 문장당 한 번만 함수를 평가하고 행 간에 결과를 재사용할 수 있습니다. 비결정적 함수를 잘못 결정적으로 표시하면 서버가 실제로 다른 출력을 생성해야 하는 입력에 대해 동일한 결과를 반환할 수 있습니다. 외부 상태, 난수, 시간에 의존하지 않는 경우에만 `.deterministic()`을 추가하세요.
**빌더 서명:** `.deterministic(bool d = true)` — 인수 없이 사용하면 기본값이 `true`입니다.
**예시:**
```cpp theme={null}
.func(make_func<&complex_add_impl>("complex_add")
.returns(COMPLEX)
.param(COMPLEX)
.param(COMPLEX)
.deterministic()
.build())
```
`complex_add`가 결정적이라고 선언되었으므로 생성된 열 정의에서 사용할 수 있습니다:
```sql theme={null}
-- Deterministic VDFs can be used in generated columns
CREATE TABLE t (
a COMPLEX,
b COMPLEX,
result COMPLEX GENERATED ALWAYS AS (complex_add(a, b)) STORED
);
-- STORED vs VIRTUAL follows standard MySQL generated column rules
```
### 사용자 정의 버퍼 크기
변수 길이 데이터를 반환하는 함수의 경우 특정 버퍼 크기 요청:
```cpp theme={null}
make_func<&large_result_impl>("large_result")
.returns(STRING)
.param(INT)
.buffer_size(65536) // Request 64KB buffer
.build()
```
쓰기 전에 사용 가능한 버퍼 공간 확인:
```cpp theme={null}
void large_result_impl(StringArg input, StringResult out) {
if (input.is_null()) { out.set_null(); return; }
size_t needed = calculate_output_size(input.value());
auto buf = out.buffer();
if (needed > buf.size()) {
out.error("Output exceeds buffer size");
return;
}
// Write output into buf.data()
out.set_length(actual_output_length);
}
```
`.buffer_size()`를 통해 함수의 최대 출력 크기에 기반하여 충분한 버퍼 크기 요청.
함수 구현 전에 [확장 API 참조](/docs/ko/mysql-8.4/0.0.4/extension-api-reference)를 검토하여 VDF 계약(널 검사, 결과 유형, 버퍼 크기, 오류 처리)을 완전히 이해하세요.
## 단계 4: 사용자 정의 유형 만들기
사용자 정의 유형을 통해 새 열 유형(예: `COMPLEX`, `UUID`, `VECTOR`)을 정의할 수 있습니다. 이 유형은 `ORDER BY`, 인덱스, 집계 함수와 함께 작동합니다. 확장이 단순히 함수만 등록하는 경우 단계 5로 건너뜁니다.
자세한 구현은 [사용자 정의 유형 만들기](/docs/ko/mysql-8.4/0.0.4/custom-types)를 참조하세요. 유형이 매개변수를 받는 경우(예: `VECTOR(1536)`) [파라미터화된 유형](/docs/ko/mysql-8.4/0.0.4/development#parameterized-types)을 참조하세요.
단계 5: 빌드 구성 업데이트
`CMakeLists.txt`를 편집하여 확장을 VEB 파일로 빌드:
```cmake theme={null}
cmake_minimum_required(VERSION 3.18)
project(my_extension)
# Find VillageSQL Extension Framework
find_package(VillageSQLExtensionFramework QUIET)
# The framework detects build flags via 4 methods (in order):
# 1. Explicit MYSQL_INCLUDE_FLAGS/MYSQL_CXXFLAGS
# 2. VillageSQL_BUILD_DIR (reads CMakeCache.txt from VillageSQL build)
# 3. VSQL_BASE_DIR (uses mysql_config)
# 4. Default - mysql_config from PATH
# Build shared library with your source files
add_library(extension SHARED
src/extension.cc
src/my_functions.cc
)
# Create VEB archive
VEF_CREATE_VEB(
NAME my_extension
LIBRARY_TARGET extension
MANIFEST ${CMAKE_CURRENT_SOURCE_DIR}/manifest.json
)
# Install VEB to VillageSQL extensions directory
install(FILES ${VEB_OUTPUT} DESTINATION ${INSTALL_DIR})
```
**구성 참고 사항:**
* `VillageSQLExtensionFramework`는 확장 빌드를 위한 CMake 도구 제공
* `VEF_CREATE_VEB()`는 라이브러리, 매니페스트, 메타데이터를 `.veb` 아카이브로 패키징
* 프레임워크는 MySQL/VillageSQL 빌드 플래그 자동 감지
* 라이브러리 타겟 이름은 일반적으로 `extension`(어떤 이름이든 가능)
* VEB 이름은 `manifest.json` 이름과 일치해야 함
* 기본적으로 확장은 안정적 ABI 헤더에 맞춰 빌드됩니다. 불안정한 개발 헤더로 빌드하려면 `-DVSQL_USE_DEV_ABI=ON` 설정
***
## 단계 6: 빌드 디렉토리 생성
별도의 빌드 디렉토리 생성:
```bash theme={null}
mkdir build
cd build
```
## 단계 7: CMake 및 Make로 빌드
확장 구성 및 빌드:
```bash theme={null}
# Configure the build
cmake ..
# Or, if building against VillageSQL source:
cmake .. -DVillageSQL_BUILD_DIR=/path/to/villagesql/build
# Or, to build against the unstable dev ABI headers:
cmake .. -DVSQL_USE_DEV_ABI=ON
# Build the extension
make
```
이로 인해 생성되는 파일:
* 컴파일된 공유 라이브러리(`.so` 파일)
* VEB 패키지(`.veb` 파일) - 매니페스트와 라이브러리를 포함하는 tar 아카이브
### 빌드 검증
VEB 파일 내용 확인:
```bash theme={null}
make show_veb
```
다음과 같은 내용이 표시되어야 합니다:
```
manifest.json
lib/myext.so
```
## 단계 8: 설치 및 테스트
### 옵션 A: VillageSQL 확장 디렉토리에 설치
설치 타겟을 사용하여 VEB를 VillageSQL 설치 디렉토리로 복사:
```bash theme={null}
make install
```
이것은 `.veb` 파일을 `VillageSQL_VEB_INSTALL_DIR`로 구성된 디렉토리로 복사합니다.
### 옵션 B: 수동 설치
VEB 파일 수동 복사:
```bash theme={null}
# Find the VEF directory
mysql -u root -p -e "SHOW VARIABLES LIKE 'veb_dir';"
# Copy the VEB file
sudo cp my-awesome-extension.veb /path/to/veb_dir/
```
### 확장 테스트
1. **VillageSQL에 연결**:
```bash theme={null}
mysql -u root -p
```
2. **확장 설치**:
```sql theme={null}
INSTALL EXTENSION my_awesome_extension;
```
3. **설치 확인**:
```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```
4. **함수 테스트**:
```sql theme={null}
SELECT my_reverse('Hello, World!');
-- Output: !dlroW ,olleH
SELECT count_vowels('VillageSQL');
-- Output: 3
```
## 테스트 만들기
확장이 올바르게 작동하는지 검증하기 위해 테스트 파일 추가:
1. `mysql-test/t/`에 테스트 파일 생성:
```sql theme={null}
-- mysql-test/t/my_basic.test
SELECT my_reverse('abc');
SELECT my_reverse('');
SELECT my_reverse(NULL);
```
2. 예상 결과 생성:
```bash theme={null}
cd /path/to/villagesql/build/mysql-test
perl mysql-test-run.pl --suite=/path/to/your/extension/mysql-test --record
```
3. 테스트 실행:
```bash theme={null}
perl mysql-test-run.pl --suite=/path/to/your/extension/mysql-test
```
## 문제 해결
### 확장 불로드
오류 로그 확인 및 VEB 내용 검증:
```bash theme={null}
make show_veb
tail -f /var/log/mysql/error.log
```
### 함수 찾기 실패
설치 및 등록 확인:
```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```
### 빌드 오류
```bash theme={null}
# Verify mysql_config is available
which mysql_config
mysql_config --version
# Check compiler version
gcc --version # or clang --version
# Verify CMake version (3.18+ required)
cmake --version
```
## 예제 확장
기존 VillageSQL 확장에서 배우세요:
복소수 데이터 유형 구현
확장 생성을 위한 최소 템플릿
## 다음 단계
확장 설치 및 관리 방법 배우기
유형 래퍼, 집계, 시스템 변수, 테스트
라이프사이클, 캐싱, 성능, 보안 모델
VillageSQL 소스 코드로 빌드하기
## 참고 자료
* [VillageSQL 확장 템플릿](https://github.com/villagesql/vsql-extension-template)
* [MySQL UDF API 문서](https://dev.mysql.com/doc/extending-mysql/8.4/en/adding-loadable-function.html)
* [CMake 문서](https://cmake.org/documentation/)
* [VillageSQL 커뮤니티 Discord](https://discord.gg/KSr6whd3Fr)