> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 이전 프로토콜

> VEF 프로토콜이 무엇인지, 서버가 확장을 로드할 때 프로토콜을 어떻게 선택하는지 설명하고, 프로토콜 1과 3에 대한 참조를 제공합니다.

서버가 확장의 함수를 호출할 때, 서버는 고정된 C 구조체 집합을 통해 인자를 전달하고 결과를 읽어 옵니다. 사용자 정의 유형도 같은 방식으로 동작합니다. 확장은 각 유형을 구조체로 기술하고, 서버는 확장을 설치할 때와 서버가 시작할 때마다 그 구조체를 읽습니다. 프로토콜은 이러한 구조체와 구조체를 채우는 규칙에 번호를 붙인 버전입니다.

새 프로토콜은 이전 확장이 읽는 필드를 옮기지 않고 구조체에 내용을 추가하며, 서버는 이전의 각 안정 프로토콜을 읽는 코드를 계속 유지합니다. 그래서 서버는 이전 프로토콜용으로 빌드된 확장을 여전히 로드할 수 있습니다.

프로토콜 번호는 직접 설정하지 않습니다. 확장을 빌드하는 데 사용하는 SDK가 번호를 정합니다. 각 SDK 릴리스는 하나의 안정 프로토콜용으로 확장을 빌드하고, 그 SDK의 개발 헤더(`-DVSQL_USE_DEV_ABI=ON`)는 개발 프로토콜용으로 빌드합니다. 확장을 더 새로운 프로토콜로 옮기려면 더 새로운 SDK로 재빌드하세요.

## 서버가 프로토콜을 선택하는 방법

확장을 설치할 때, 서버는 자체 최신 프로토콜을 제시하고 확장은 빌드 대상 프로토콜을 선언합니다. 그러면 서버와 확장은 두 번호 중 낮은 쪽을 사용합니다. 예를 들어 프로토콜 4를 제시하는 서버는 프로토콜 3용으로 빌드된 확장과 프로토콜 3으로 통신하며, 프로토콜 4가 추가하는 기능을 그 확장에 제공하지 않습니다.

설치된 각 확장의 프로토콜을 보려면 `INFORMATION_SCHEMA.EXTENSION_REGISTRATION`을 조회하세요:

```sql theme={null}
SELECT EXTENSION_NAME, NEGOTIATED_PROTOCOL
FROM INFORMATION_SCHEMA.EXTENSION_REGISTRATION;
```

`NEGOTIATED_PROTOCOL` 열에는 서버와 확장이 합의한 프로토콜이 들어 있습니다.

## 안정 프로토콜과 개발 프로토콜

홀수 번호 프로토콜은 안정 프로토콜입니다. 현재 서버는 프로토콜 1까지 거슬러 올라가 모든 안정 프로토콜을 받아들이므로, 안정 프로토콜용으로 빌드한 확장은 재빌드 없이 더 새로운 서버에도 계속 설치됩니다.

짝수 번호 프로토콜은 개발 버전입니다. 서버는 자체 개발 프로토콜만 받아들이며, 그 프로토콜의 구조체는 서버 빌드 간에 바뀔 수 있습니다. 개발 헤더(`-DVSQL_USE_DEV_ABI=ON`)로 빌드한 확장은 서버를 업데이트한 뒤 동작을 멈출 수 있습니다. 그런 경우 새 서버에 맞춰 재빌드하세요.

릴리스가 개발 프로토콜을 다음 안정 번호로 승격하면, 서버는 이전 개발 번호를 더 이상 받아들이지 않습니다. 그러면 `INSTALL EXTENSION`은 `extension uses obsolete unstable protocol version` 뒤에 이전 번호와 현재 번호가 붙은 오류로 실패합니다. 서버가 시작할 때도 같은 검사가 실행되므로, 그런 확장이 설치되어 있는 동안에는 서버가 시작하지 않습니다. 서버를 업그레이드하기 전에, 개발 헤더로 빌드한 각 확장을 새 릴리스에 맞춰 재빌드하세요.

| 프로토콜 | 상태 | 빌드하는 SDK |
| - | - | - |
| 1 | 안정 | SDK 0.0.1부터 0.0.3까지 |
| 2 | 지원되지 않음 | 0.0.3의 개발 헤더 |
| 3 | 안정 | SDK 0.0.4부터 0.0.7까지 |
| 4 | 개발 | 0.0.4부터 0.0.7까지의 개발 헤더 |

> [!NOTE]
>
> **0.0.8-dev에서 변경됨.** 프로토콜 4는 안정 프로토콜 5가 되며, SDK 0.0.8이 이를 빌드합니다. 0.0.8의 개발 헤더는 프로토콜 6을 빌드합니다. 서버는 프로토콜 4를 거부하며, 프로토콜 4는 지원되지 않습니다. 프로토콜 1과 3은 사용 중단됩니다. 서버는 여전히 이들을 받아들이지만, 새로운 확장은 프로토콜 5를 사용해야 합니다.

## 프로토콜 3

SDK 0.0.4부터 0.0.7까지는 프로토콜 3 확장을 빌드합니다.

> [!NOTE]
>
> **0.0.8-dev에서 변경됨.** 이러한 SDK 중 하나로 빌드한 확장은 더 새로운 서버에서도 같은 동작으로 계속 작동하며, 재빌드할 필요가 없습니다.
>
> 0.0.8 SDK로 재빌드하면 확장은 프로토콜 5로 옮겨 가고 다음 기능을 사용할 수 있습니다:
>
> * `.max_result_length()`: STRING 또는 BINARY 함수의 결과 열 크기를 지정하여, 구체화된 결과가 인자 폭에서 잘리지 않도록 합니다.
> * [로드 및 언로드 훅](https://villagesql.com/docs/ko/sdk/cpp/development.md#extension-load-and-unload-hooks), `.on_init()`과 `.on_deinit()`.
> * [가변 길이 사용자 정의 유형](https://villagesql.com/docs/ko/sdk/cpp/type-operations.md#variable-length-types), `.variable_length_type()`.
> * 원시 바이트를 위한 `BINARY` 매개변수 및 결과 유형.
> * 사용자 정의 유형의 바이너리 형식, `.from_binary()`와 `.to_binary()`. SQL에서 `TYPE::from_binary`와 `TYPE::to_binary`로 호출할 수 있습니다.
> * 상수 인자의 값을 볼 수 있는 prerun.
> * [해석 시점의 타입 검사](https://villagesql.com/docs/ko/sdk/cpp/development.md#deciding-a-functions-type-parameters-at-resolution-time), `.bind_and_check_types()`.
> * 버퍼보다 큰 STRING 값을 온전히 반환하는 `out.set()`. 프로토콜 3에서는 값이 잘립니다.
> * 함수를 벗어난 예외는 문을 오류로 실패시킵니다.
>
> 재빌드하면 한 가지 동작이 바뀝니다. 프로토콜 3과 프로토콜 5는 STRING 인자를 서로 다르게 전달합니다. 프로토콜 3 함수는 인자의 바이트를 인자 자체의 문자 집합 그대로 변경 없이 받습니다. 프로토콜 5 함수는 서버가 호출자의 문자 집합에서 변환한 utf8mb4 텍스트로 인자를 받습니다. 예를 들어 latin1 문자열 `_latin1 X'E9'`(é)는 프로토콜 3 함수에는 단일 바이트 `E9`로 도달하고, 프로토콜 5 함수에는 두 바이트 `C3 A9`로 도달합니다. 인자가 유효한 utf8mb4가 아닌 바이너리 문자열이면 문이 실패합니다:
>
> ```text theme={null}
> ERROR 3854 (HY000) at line 1: Cannot convert string '\xFF\x00' from binary to utf8mb4
> ```
>
> 재빌드하기 전에, 해시 함수나 암호화 함수처럼 STRING 인자에서 원시 바이트를 읽는 각 함수를 찾아 그 매개변수를 `BINARY`로 선언하세요. [프로토콜 1 스타일](#protocol-1)로 작성된 확장에도 같은 내용이 적용됩니다.

## 프로토콜 1

프로토콜 1은 0.0.1부터 안정 프로토콜이었습니다. 서버는 여전히 프로토콜 1을 받아들이지만, 향후 릴리스에서 사용 중단될 가능성이 있습니다. 새로운 확장은 [C++로 확장 만들기](https://villagesql.com/docs/ko/extensions/build/create.md) 및 [C++ 개발](https://villagesql.com/docs/ko/sdk/cpp/development.md) 가이드의 타입화된 API로 작성하세요. 이 절은 프로토콜 1 스타일로 작성된 기존 확장을 위한 참조입니다. 더 새로운 SDK도 그 스타일을 여전히 컴파일하며, 확장을 해당 SDK의 안정 프로토콜용으로 빌드합니다.

> [!NOTE]
>
> **0.0.8-dev에서 변경됨.** 프로토콜 1은 사용 중단됩니다. 서버는 여전히 프로토콜 1을 받아들이지만, 새로운 확장은 프로토콜 5를 사용해야 합니다.

### 함수 포인터 기반 유형 API

프로토콜 1 사용자 정의 유형은 `vsql::make_type<>` 템플릿 대신 명시적인 함수 포인터를 사용하여 등록됩니다. 함수 서명은 타입화된 API의 상응하는 서명과 다릅니다. 원시 포인터와 길이를 인자로 받으며, `Arg` 및 `Result` 객체는 받지 않습니다.

#### 함수 서명

```cpp theme={null}
// Encode: Convert string representation to binary.
// Returns false on success, true on error.
bool encode_mytype(unsigned char* buffer, size_t buffer_size,
                   const char* from, size_t from_len, size_t* length) {
    // Parse 'from' string and write binary to 'buffer'.
    // Set *length to bytes written.
    // Return false on success, true on error (e.g., set *length = 0).
}

// Decode: Convert binary to string representation.
// Returns false on success, true on error.
bool decode_mytype(const unsigned char* buffer, size_t buffer_size,
                   char* to, size_t to_size, size_t* to_length) {
    // Read binary from 'buffer' and write string to 'to'.
    // Set *to_length to string length.
    // Return false on success, true on error.
}

// Compare: enables ORDER BY and indexing (required).
int compare_mytype(const unsigned char* data1, size_t len1,
                   const unsigned char* data2, size_t len2) {
    // Return: negative if data1<data2, 0 if equal, positive if data1>data2.
}

// Hash: custom hash (optional, uses default binary hash if omitted).
size_t hash_mytype(const unsigned char* data, size_t len) {
    // Return hash value for the binary data.
}
```

#### 등록

이 형식은 `#include <villagesql/extension.h>`(`<villagesql/vsql.h>`가 아님)와 `using namespace villagesql;`를 필요로 합니다.

```cpp theme={null}
#include <villagesql/extension.h>
using namespace villagesql;

constexpr const char* MYTYPE = "mytype";

VEF_GENERATE_ENTRY_POINTS(
  make_extension()
    .type(make_type(MYTYPE)
      .persisted_length(16)              // Fixed storage size in bytes
      .max_decode_buffer_length(64)      // Max string representation size
      .encode(&encode_mytype)
      .decode(&decode_mytype)
      .compare(&compare_mytype)          // Enables ORDER BY and indexes
      .hash(&hash_mytype)                // Optional custom hash
      .build())
    .func(make_func<&mytype_constructor>("MYTYPE")  // Constructor function
      .returns(MYTYPE)
      .param(REAL)
      .param(REAL)
      .build())
);
```

컴파일 타임 문자열 NTTP를 사용하는 `vsql::make_type<kMyTypeName>()`이 선호되는 형식입니다. `make_type(MYTYPE)`(템플릿 매개변수 없음)은 프로토콜 1 형식으로, 계속 지원되지만 향후 릴리스에서 사용 중단될 가능성이 있습니다.

### 원시 ABI 스타일 (함수)

프로토콜 1 VDF 구현은 타입화된 래퍼를 사용하는 대신 원시 C 구조체를 직접 전달할 수 있습니다. 이 스타일은 계속 지원되지만 향후 릴리스에서 사용 중단될 가능성이 있습니다. 모든 새로운 코드에 [타입화된 인자/결과 API](https://villagesql.com/docs/ko/sdk/cpp/development.md#argument-and-result-types)를 사용하세요.

```cpp theme={null}
#include <villagesql/extension.h>
using namespace villagesql;

void add_impl(vef_context_t* ctx,
              vef_invalue_t* a, vef_invalue_t* b,
              vef_vdf_result_t* result) {
  if (a->is_null || b->is_null) {
    result->type = VEF_RESULT_NULL;
    return;
  }
  result->int_value = a->int_value + b->int_value;
  result->type = VEF_RESULT_VALUE;
}

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .func(make_func<&add_impl>("add_impl")
                  .returns(INT)
                  .param(INT)
                  .param(INT)
                  .build()))
```

이 인자별 원시 서명 — `void(vef_context_t*, vef_invalue_t* arg0, ..., vef_vdf_result_t*)` — 은 `<villagesql/extension.h>`의 `make_func<>()`에서만 감지됩니다. `<villagesql/vsql.h>`의 `make_func<>()`는 원시 `vef_context_t*`/`vef_invalue_t*`/`vef_vdf_result_t*` 서명을 컴파일 타임에 모두 거부합니다.

#### 결과 상수

원시 ABI는 `result->type`에 설정된 `vef_return_value_type_t`를 통해 결과 상태를 전달합니다:

| 상수 | 값 | 의미 |
| - | - | - |
| `VEF_RESULT_VALUE` | 0 | 성공 — 출력이 적절한 유니온 필드에 있습니다 |
| `VEF_RESULT_NULL` | 1 | 결과가 SQL NULL입니다 |
| `VEF_RESULT_WARNING` | 2 | 행 수준 경고 — 실행이 계속되고, 이 행에 대해 NULL이 반환되며, SQL 경고(3200)가 추가됩니다 |
| `VEF_RESULT_ERROR` | 3 | 치명적 오류 — 명령문 실행이 중단됩니다. 메시지는 `result->error_msg`에 있습니다 |

타입화된 API에서는 `out.set()`, `out.set_null()`, `out.warning()`, `out.error()`가 이를 자동으로 처리합니다.

#### 프로토콜 1에서의 집계 등록

`<villagesql/extension.h>`의 `make_func<>()` 빌더에는 `.clear<>()`나 `.accumulate<>()` 멤버가 없습니다. 이 메서드들은 `<villagesql/vsql.h>`의 별도 빌더인 `make_aggregate_func<State, &result_fn>()`에만 존재하며, 이 빌더는 원시 `vef_context_t*`/`vef_vdf_args_t*` 포인터 대신 `State&` 기반의 타입화된 서명을 사용합니다. 모든 새로운 코드에 [타입화된 집계 접근법](https://villagesql.com/docs/ko/sdk/cpp/development.md#aggregate-vdfs)을 사용하세요. `VEF_PROTOCOL_3` 이상의 원시 등록은 `vef_func_desc_t`의 `clear`와 `accumulate` 콜백을 직접 설정할 수도 있습니다.

```cpp theme={null}
#include <villagesql/vsql.h>
#include <optional>
using namespace vsql;

using SumState = std::optional<long long>;

void my_clear(SumState &s) { s = std::nullopt; }
void my_acc(SumState &s, IntArg v) {
  if (!v.is_null()) s = s.value_or(0) + v.value();
}
void my_result(const SumState &s, IntResult out) {
  if (!s.has_value()) { out.set_null(); return; }
  out.set(s.value());
}

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .func(make_aggregate_func<SumState, &my_result>("my_agg")
                  .returns(INT).param(INT)
                  .clear<&my_clear>()        // void(SumState&)
                  .accumulate<&my_acc>()     // void(SumState&, IntArg)
                  .build()))
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.