-DVSQL_USE_DEV_ABI=ON)は開発プロトコル向けにビルドします。拡張機能を新しいプロトコルへ移行するには、新しい SDK で再構築します。
サーバーがプロトコルを選ぶ方法
拡張機能をインストールするとき、サーバーは自身の最新のプロトコルを提示し、拡張機能はどのプロトコル向けにビルドされたかを宣言します。サーバーと拡張機能は、2 つの番号のうち低いほうを使用します。たとえば、プロトコル 4 を提示するサーバーは、プロトコル 3 向けにビルドされた拡張機能とはプロトコル 3 で通信し、プロトコル 4 が追加する機能をその拡張機能には提供しません。 インストール済みの各拡張機能のプロトコルを確認するには、INFORMATION_SCHEMA.EXTENSION_REGISTRATION に問い合わせます。
NEGOTIATED_PROTOCOL 列には、サーバーと拡張機能が合意したプロトコルが格納されます。
安定プロトコルと開発プロトコル
奇数番号のプロトコルは安定版です。現在、サーバーはプロトコル 1 までさかのぼってすべての安定プロトコルを受け入れるため、安定プロトコル向けにビルドした拡張機能は、再構築なしで新しいサーバーにも引き続きインストールできます。 偶数番号のプロトコルは開発版です。サーバーは自身の開発プロトコルのみを受け入れ、そのプロトコルの構造体はサーバーのビルド間で変わることがあります。開発ヘッダー(-DVSQL_USE_DEV_ABI=ON)でビルドした拡張機能は、サーバーを更新した後に動作しなくなることがあります。その場合は、新しいサーバーに対して再構築してください。
リリースによって開発プロトコルが次の安定番号に昇格すると、サーバーは古い開発番号を受け入れなくなります。その後は INSTALL EXTENSION が、extension uses obsolete unstable protocol version に古い番号と現在の番号を続けたエラーで失敗します。同じチェックはサーバーの起動時にも実行されるため、そのような拡張機能がインストールされたままのサーバーは起動しません。サーバーをアップグレードする前に、開発ヘッダーでビルドした各拡張機能を新しいリリースに対して再構築してください。
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 の拡張機能をビルドします。0.0.8-dev での変更点。 これらの SDK のいずれかでビルドした拡張機能は、新しいサーバーでも引き続き同じように動作し、再構築する必要はありません。0.0.8 SDK で再構築すると、拡張機能はプロトコル 5 に移行し、次の機能を使用できます。再構築する前に、ハッシュ関数や暗号化関数など、STRING 引数から生のバイト列を読み取る各関数を見つけ、そのパラメータを
.max_result_length()。STRING または BINARY 関数の結果列のサイズを指定し、マテリアライズされた結果が引数の幅で切り詰められないようにします。- ロードフックとアンロードフック、
.on_init()と.on_deinit()。 - 可変長カスタム型、
.variable_length_type()。 - 生のバイト列のための
BINARYパラメータと結果型。 - カスタム型のバイナリ形式、
.from_binary()と.to_binary()。SQL からTYPE::from_binaryとTYPE::to_binaryとして呼び出せます。 - 定数引数の値を参照できる prerun。
- 解決時の型チェック、
.bind_and_check_types()。 - バッファより大きい STRING 値を切り詰めずに全体を返す
out.set()。プロトコル 3 ではその値が切り詰められます。 - 関数の外へ送出された例外は、ステートメントをエラーで失敗させます。
_latin1 X'E9'(é)は、プロトコル 3 の関数には 1 バイトの E9 として届き、プロトコル 5 の関数には 2 バイトの C3 A9 として届きます。引数が有効な utf8mb4 ではないバイナリ文字列の場合、ステートメントは失敗します。BINARY として宣言してください。同じことは、プロトコル 1 スタイルで書かれた拡張機能にも当てはまります。プロトコル 1
プロトコル 1 は 0.0.1 から安定版です。サーバーは引き続きプロトコル 1 を受け入れますが、将来のリリースで非推奨になる可能性があります。新しい拡張機能は、C++での拡張機能の作成 および C++ 開発 ガイドにある型付き API で書いてください。このセクションは、プロトコル 1 スタイルで書かれた既存の拡張機能のためのリファレンスです。新しい SDK でもそのスタイルはコンパイルでき、拡張機能はその SDK 自身の安定プロトコル向けにビルドされます。0.0.8-dev での変更点。 プロトコル 1 は非推奨になります。サーバーは引き続きプロトコル 1 を受け入れますが、新しい拡張機能ではプロトコル 5 を使用してください。
関数ポインタによる型 API
プロトコル 1 のカスタム型は、vsql::make_type<> テンプレートの代わりに、明示的な関数ポインタを使用して登録されます。関数シグネチャは、型付き API の対応する関数とは異なります。生のポインタと長さを受け取り、Arg および Result オブジェクトは受け取りません。
関数シグネチャ
登録
この形式では、#include <villagesql/extension.h>(<villagesql/vsql.h> ではありません)と using namespace villagesql; が必要です。
vsql::make_type<kMyTypeName>() (コンパイル時の文字列 NTTP を使用) が推奨される形式です。make_type(MYTYPE) (テンプレートパラメータなし) はプロトコル 1 の形式であり、引き続きサポートされていますが、将来のリリースで非推奨になる可能性があります。
生の ABI スタイル (関数)
プロトコル 1 の VDF 実装では、型付きラッパーを使用する代わりに、生の C 構造体を直接渡すことができます。このスタイルは引き続きサポートされていますが、将来のリリースで非推奨になる可能性があります。すべての新しいコードでは、型付き引数/結果 API を使用してください。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 を介して結果の状態を伝達します。
型付き 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& ベースの型付きシグネチャを使用します。すべての新しいコードでは、型付き集計関数のアプローチ を使用してください。VEF_PROTOCOL_3 以降の生の登録では、vef_func_desc_t の clear および accumulate コールバックを手動で設定することもできます。