> ## 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 リリースは 1 つの安定プロトコル向けに拡張機能をビルドし、その開発ヘッダー（`-DVSQL_USE_DEV_ABI=ON`）は開発プロトコル向けにビルドします。拡張機能を新しいプロトコルへ移行するには、新しい SDK で再構築します。

## サーバーがプロトコルを選ぶ方法

拡張機能をインストールするとき、サーバーは自身の最新のプロトコルを提示し、拡張機能はどのプロトコル向けにビルドされたかを宣言します。サーバーと拡張機能は、2 つの番号のうち低いほうを使用します。たとえば、プロトコル 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 はプロトコル 5 向けにビルドします。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/ja/sdk/cpp/development.md#extension-load-and-unload-hooks)、`.on_init()` と `.on_deinit()`。
> * [可変長カスタム型](https://villagesql.com/docs/ja/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/ja/sdk/cpp/development.md#deciding-a-functions-type-parameters-at-resolution-time)、`.bind_and_check_types()`。
> * バッファより大きい STRING 値を切り詰めずに全体を返す `out.set()`。プロトコル 3 ではその値が切り詰められます。
> * 関数の外へ送出された例外は、ステートメントをエラーで失敗させます。
>
> 再構築すると変わる動作が 1 つあります。プロトコル 3 とプロトコル 5 では、STRING 引数の渡し方が異なります。プロトコル 3 の関数は、引数のバイト列を引数自身の文字セットのまま変更なしで受け取ります。プロトコル 5 の関数は、サーバーが呼び出し元の文字セットから変換した utf8mb4 テキストとして引数を受け取ります。たとえば、latin1 文字列 `_latin1 X'E9'`（é）は、プロトコル 3 の関数には 1 バイトの `E9` として届き、プロトコル 5 の関数には 2 バイトの `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/ja/extensions/build/create.md) および [C++ 開発](https://villagesql.com/docs/ja/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())
);
```

`vsql::make_type<kMyTypeName>()` (コンパイル時の文字列 NTTP を使用) が推奨される形式です。`make_type(MYTYPE)` (テンプレートパラメータなし) はプロトコル 1 の形式であり、引き続きサポートされていますが、将来のリリースで非推奨になる可能性があります。

### 生の ABI スタイル (関数)

プロトコル 1 の VDF 実装では、型付きラッパーを使用する代わりに、生の C 構造体を直接渡すことができます。このスタイルは引き続きサポートされていますが、将来のリリースで非推奨になる可能性があります。すべての新しいコードでは、[型付き引数/結果 API](https://villagesql.com/docs/ja/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/ja/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.