> ## 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. # プレビュー機能 > プレビュー機能は、APIが最終化される前に拡張機能にサーバー機能へのアクセスを提供します。このページでは、プレビュー層の有効化、keyring、status_var、sys_var、thread_worker、sql_query、statement_event機能の設定方法と登録パターンについて説明します。 プレビュー機能は、APIが最終化される前に拡張機能に公開されるサーバー機能です。プレビュー機能を宣言する拡張機能は、`vsql_allow_preview_extensions = ON` が設定されている場合にのみインストールできます（[プレビュー層の有効化](#enabling-the-preview-tier)を参照）—プレビュー機能を使用しない拡張機能は、この設定に関係なく通常通りインストールされます。 プレビュー機能APIは安定していません。プレビュー機能に依存して構築された拡張機能は、サーバーのアップデート後にロードに失敗する可能性があります。機能が安定化すると、そのヘッダーはバージョン化された安定版 C++ SDK パスに移動されます。

プレビュー層の有効化

プレビュー機能を使用する拡張機能をインストールする前に、`SET PERSIST` を使用して `vsql_allow_preview_extensions = ON` を設定します： ```sql theme={null} SET PERSIST vsql_allow_preview_extensions = ON; ``` `SET GLOBAL` はこの変数に対して拒否されます — サーバーは設定を再起動後に保持するために `SET PERSIST` を要求します。プレビュー機能を持つ拡張機能は起動時にロードされるため、サーバーが起動する時点でこの変数が ON である必要があります。 mysqld を直接起動する場合（例：サーバーを初めて起動するインストールスクリプトから）、コマンドライン引数でフラグを渡してください — `mysqld-auto.cnf` がまだ存在しないため、永続化された値を保持できません： ```bash theme={null} mysqld --vsql_allow_preview_extensions=ON ``` 無効化するには： ```sql theme={null} SET PERSIST vsql_allow_preview_extensions = OFF; ``` プレビュー機能を使用する拡張機能が現在インストールされている場合、失敗します。まずそれらの拡張機能をアンインストールし、その後設定をオフにします。 ## 機能インデックス | 機能 | ヘッダー | 状態 | | -------------------------------- | ---------------------------------------- | ----- | | `vsql::preview::column_store` | `` | プレビュー | | `vsql::preview::keyring` | `` | プレビュー | | `vsql::preview::sql_query` | `` | プレビュー | | `vsql::preview::statement_event` | `` | プレビュー | | `vsql::preview::status_var` | `` | プレビュー | | `vsql::preview::storage` | `` | プレビュー | | `vsql::preview::sys_var` | `` | プレビュー | | `vsql::preview::thread_worker` | `` | プレビュー | ## 登録パターン プレビュー機能を使用するには、ファイルスコープで機能オブジェクトを値として宣言し、`make_extension()` 内の `.with()` に参照で渡します。サーバーは登録時にオブジェクトの `abi` ポインタを設定します： ```cpp theme={null} #include #include using KeyringCapability = vsql::preview_keyring::KeyringCapability; static KeyringCapability g_keyring; VEF_GENERATE_ENTRY_POINTS( make_extension() .func(/* ... */) .with(g_keyring)) ``` `.with(capability)` はサーバーに拡張機能が必要とする機能を伝えます。拡張機能をインストールする際に `vsql_allow_preview_extensions` がオフの場合、サーバーはその機能名を示すエラーを返してインストールを拒否します。 拡張機能内で宣言されたすべての機能オブジェクトは、`.with()` に正確に1回渡す必要があります。ロード時にサーバーは宣言されたすべての機能インスタンスを `.with()` が受け取った内容と照合し、ルール違反の場合 `INSTALL EXTENSION` を失敗させます： * **宣言されたが `.with()` に渡されなかった場合：** `capability '' was declared but never passed to .with(); every CapabilityBase-derived static must be registered via .with(cap) in the extension builder` * **同じインスタンスを `.with()` に複数回渡した場合：** `capability '' passed to .with() more than once` * **`.with()` に渡されたオブジェクトが機能でない場合：** `.with() received an object that does not inherit vsql::detail::CapabilityBase; not a registered capability` 完全なエラーは `Failed to load VEF extension '': vef_register returned an error: ` として表示されます。

Keyring アクセス

keyring 機能（`vsql::preview::keyring`）は、MySQL keyring コンポーネントに格納されたシークレットを拡張機能が読み書きできるようにします。APIキー、暗号化キー、またはSQLテーブルに保存したくないその他のシークレットに使用します。 機能名 `VEF_PREVIEW_KEYRING_NAME` は `"vsql::preview::keyring"` です。 読み書きが成功するには、MySQLサーバーに keyring コンポーネントがインストールされている必要があります。インストールされていない場合、操作は `KeyringCapability::Status::UNAVAILABLE` を返します。 ### ステータス値 `KeyringCapability::Status` は `read()`（`ReadResult` 内）および `write()` から返されるスコープ付き列挙型です： | ステータス | 意味 | | --------------------- | ------------------------------ | | `Status::OK` | 操作が成功しました。 | | `Status::NOT_FOUND` | キーが存在しません（読み取りのみ）。 | | `Status::UNAVAILABLE` | keyring コンポーネントがインストールされていません。 | | `Status::ERROR` | その他の失敗。 | ### 機能の宣言 ヘッダーを含め、ファイルスコープで機能オブジェクトを宣言し、`.with()` に渡します： ```cpp theme={null} #include #include using KeyringCapability = vsql::preview_keyring::KeyringCapability; static KeyringCapability g_keyring; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_keyring)) ``` `g_keyring` オブジェクトはロード時にサーバーによって初期化されます。keyring コンポーネントがインストールされていない場合、`read()` および `write()` は実行時に `Status::UNAVAILABLE` を返します — 別の利用可能性チェックで処理をガードする代わりに、各呼び出しでステータスを確認してください。 ### 読み書き ```cpp theme={null} struct KeyringCapability::ReadResult { KeyringCapability::Status status; std::string value; }; [[nodiscard]] KeyringCapability::ReadResult KeyringCapability::read(std::string_view data_id, std::string_view auth_id = {}) const; [[nodiscard]] KeyringCapability::Status KeyringCapability::write(std::string_view data_id, std::string_view auth_id, std::string_view data) const; ``` `data_id` はキー識別子です。`auth_id` は所有ユーザーです — 内部キー（特定のユーザーに関連付けられていない）を読み書きするには空文字列（または `read` では省略、デフォルトは `{}`）を渡します。 `read` は値で `ReadResult` を返します。構造化バインディングでバインドします： ```cpp theme={null} auto [status, value] = g_keyring.read("my_secret"); if (status == KeyringCapability::Status::OK) { // value contains the secret bytes } ``` `Status::OK` 以外のステータスの場合、`value` は空です。 `write` は直接 `Status` を返し、`data` を `data_id` / `auth_id` で格納します。 ### 完全な例 これはサーバーに同梱される `vsql_keyring_reader` テスト拡張機能の簡略化されたバージョンです。2つの VDF を登録します：`keyring_read` および `keyring_store`。 ```cpp theme={null} #include #include using namespace vsql; using KeyringCapability = vsql::preview_keyring::KeyringCapability; static KeyringCapability g_keyring; void keyring_read(StringArg data_id, StringArg auth_id, StringResult out) { if (data_id.is_null()) { out.set_null(); return; } const auto [status, value] = g_keyring.read(data_id.value(), auth_id.is_null() ? "" : auth_id.value()); if (status == KeyringCapability::Status::UNAVAILABLE) { out.error("No keyring component is installed"); return; } if (status != KeyringCapability::Status::OK) { out.set_null(); return; } auto buf = out.buffer(); size_t len = std::min(value.size(), buf.size()); memcpy(buf.data(), value.data(), len); out.set_length(len); } void keyring_store(StringArg data_id, StringArg auth_id, StringArg value, IntResult out) { if (data_id.is_null() || value.is_null()) { out.set(1); return; } KeyringCapability::Status status = g_keyring.write( data_id.value(), auth_id.is_null() ? "" : auth_id.value(), value.value()); if (status == KeyringCapability::Status::UNAVAILABLE) { out.error("No keyring component is installed"); return; } out.set(status == KeyringCapability::Status::OK ? 0 : 1); } VEF_GENERATE_ENTRY_POINTS( make_extension() .func(make_func<&keyring_read>("keyring_read") .returns(STRING).param(STRING).param(STRING).build()) .func(make_func<&keyring_store>("keyring_store") .returns(INT).param(STRING).param(STRING).param(STRING).build()) .with(g_keyring)) ```

ステータス変数

status\_var 機能（`vsql::preview::status_var`）は、拡張機能が MySQL ステータス変数として `long long` および `double` カウンターを公開できるようにします。拡張機能はストレージを所有し、値を書き込みます。サーバーはステータス変数がクエリされるたびにポインタ経由で読み取ります。 `vsql::preview_status_var::make_capability()` で機能を構築し、`make_int(name, value_ptr)` または `make_double(name, value_ptr)` から得られる記述子のブレースリストを渡します。テンプレートはブレースリストからカウントを推測するため、明示的なサイズは必要ありません。 ### 完全な例 ```cpp theme={null} #include #include namespace sv = vsql::preview_status_var; static long long g_hits = 0; static long long g_misses = 0; static auto STATUS_VARS = sv::make_capability({ sv::make_int("ext_hits", &g_hits), sv::make_int("ext_misses", &g_misses)}); VEF_GENERATE_ENTRY_POINTS( make_extension() .with(STATUS_VARS)) ``` `make_int` には `long long *` が必要です。`make_double` には `double *` が必要です。これらがサポートされる唯一の2つの型です。 ### SQL からのアクセス `INSTALL EXTENSION my_ext` 後、変数は拡張機能名をプレフィックスとして表示されます： ```sql theme={null} SHOW GLOBAL STATUS LIKE 'my_ext%'; ``` ``` Variable_name Value my_ext.ext_hits 0 my_ext.ext_misses 0 ``` 複数のクエリスレッドが非アトミックな `++` で同時にインクリメントする場合、まれに値が失われる可能性がありますが、`SHOW STATUS` で公開される近似カウンターとしては許容されます。

システム変数

sys\_var 機能（`vsql::preview::sys_var`）は、拡張機能所有のストレージに紐付けられた MySQL システム変数を登録できるようにします。3つの型がサポートされます：`BOOL`（`bool *`）、`INT`（`long long *`）、`STR`（`char **`）。`INT` 記述子には `min_val` および `max_val` の境界が含まれます。すべての記述子にはデフォルト値とコメントが含まれます。 `vsql::preview_sys_var::make_capability()` で機能を構築し、対応するファクトリ関数 `make_bool`、`make_int`、`make_str` を使用します。機能オブジェクトは `get()` および `set()` を公開し、拡張機能コードからのプログラム的アクセスを可能にします。両方とも成功時に `false` を返します。 値の変更に反応するには、記述子に `.on_change<&fn>()` をチェーンします。コールバックは `var_name()` および型アクセス（`as_int()`、`as_real()`、`as_str()`）を備えた `sv::SysVarChange` を受け取ります。 機能オブジェクトは静的ストレージ持続期間でなければなりません。MySQL はユーザーが変数を設定する際にストレージポインタに直接書き込みます。 | ファクトリ | ストレージ型 | 追加パラメータ | | --------------- | ------------- | ------------------------------- | | `sv::make_bool` | `bool *` | `def_val` | | `sv::make_int` | `long long *` | `def_val`, `min_val`, `max_val` | | `sv::make_str` | `char **` | `def_val` | ### 完全な例 ```cpp theme={null} #include #include namespace sv = vsql::preview_sys_var; static bool g_enabled = true; static long long g_threshold = 1000; static char *g_log_file = nullptr; static void on_threshold_change(sv::SysVarChange c) { // c.var_name() identifies the variable; c.as_int() returns the new value } static auto SYS_VARS = sv::make_capability({ sv::make_bool("enabled", "Enable feature", &g_enabled, true), sv::make_int ("threshold_ms", "Threshold in ms", &g_threshold, 1000, 0, 3600000) .on_change<&on_threshold_change>(), sv::make_str ("log_file", "Log file path", &g_log_file, "/tmp/myext.log")}); VEF_GENERATE_ENTRY_POINTS( make_extension() .with(SYS_VARS)) ``` ### SQL からのアクセス `INSTALL EXTENSION my_ext` 後、変数には拡張機能名をコンポーネントプレフィックスとしてアクセスできます： ```sql theme={null} SELECT @@global.my_ext.threshold_ms; SET GLOBAL my_ext.threshold_ms = 500; SET GLOBAL my_ext.log_file = '/var/log/myext.log'; ``` ### 拡張機能コードからの読み書き INT および BOOL 変数については、グローバルストレージポインタを直接読み取ります — MySQL はそれらをアトミックに更新します。MySQL を介して変数を更新するには（ロック、範囲検証、永続化をサーバーが処理するため）、`SYS_VARS.set(extension_name, var_name, scope, value)` を呼び出します。`set` および `get` は成功時に `false` を返します。 ```cpp theme={null} bool err = SYS_VARS.set("my_ext", "threshold_ms", nullptr, value); ``` `scope` 引数は永続化を制御します： | スコープ | 動作 | | ---------------- | ---------------------------------------- | | `nullptr` | 実行中の値のみ更新、永続化されません。 | | `"PERSIST"` | 実行中の値と `mysqld-auto.cnf` に書き込みます。 | | `"PERSIST_ONLY"` | `mysqld-auto.cnf` にのみ書き込み、次回起動時に有効になります。 | ## スレッドワーカー thread worker 機能（`vsql::preview::thread_worker`）は、サーバーによって駆動されるバックグラウンドスレッドを拡張機能が実行できるようにします。スレッドは、サーバーが拡張機能ロード時に登録する制御システム変数を介して開始および停止されます。サーバーは、定期タイマー、ファイルディスクリプタの準備完了（レディ状態）、有効/無効イベントに応じて拡張機能の作業関数を呼び出します。 機能名 `VEF_PREVIEW_THREAD_WORKER_NAME` は `"vsql::preview::thread_worker"` です。 ### 機能の宣言 ヘッダーを含め、ファイルスコープで作業関数をインスタンス化した `ThreadWorkerCapability` を宣言し、`.with()` に渡します： ```cpp theme={null} #include #include static vef_next_wakeup_t my_work(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg) { // ... return {}; } static vsql::preview_thread_worker::ThreadWorkerCapability<&my_work> g_worker{"suffix"}; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_worker)) ``` 作業関数は非型テンプレート引数（`ThreadWorkerCapability<&my_work>`）として渡されるため、以下のシグネチャを持つ関数でなければなりません。最初のコンストラクタ引数はスレッド名サフィックスです。オプションの2番目の引数は制御 sys var 名をオーバーライドします。 ### 作業関数シグネチャ ```c theme={null} typedef vef_next_wakeup_t (*vef_work_fn_t)(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg); ``` `reason` はサーバーが関数を呼び出した理由を示します。`thread` はサーバー所有のハンドルです（最初の `VEF_WAKEUP_ENABLE` 呼び出し時は NULL — 以下参照）。`arg` は記述子に登録された不透明ポインタで、変更されずに渡されます。 ### Wakeup ライフサイクル サーバーは4つの理由のいずれかで作業関数を呼び出します： | 理由 | 意味 | | --------------------- | ------------------------------------------------------------------------------ | | `VEF_WAKEUP_ENABLE` | ワーカーが有効化された（制御 sys var が ON に切り替えられた）。戻り値は初期の `poll_fd` および `sleep_ms` を設定します。 | | `VEF_WAKEUP_PERIODIC` | 定期タイマーが発火（`sleep_ms` 経過）。 | | `VEF_WAKEUP_POLL_FD` | 監視中のファイルディスクリプタが読み可能になりました。 | | `VEF_WAKEUP_DISABLE` | ワーカーが無効化（制御 sys var OFF）またはサーバーがシャットダウン中。戻り値は無視されます。 | 理由が `VEF_WAKEUP_ENABLE` の場合、`thread` パラメータは NULL です。この時点でスレッドハンドルはまだ存在しないためです。他の3つの理由では `thread` は非 NULL です。 ### Wakeup 戻り値 ```c theme={null} typedef struct { unsigned int sleep_ms; int poll_fd; } vef_next_wakeup_t; ``` 作業関数は `vef_next_wakeup_t` を返し、次回のワーカー起動設定を更新します。各フィールドのゼロ値は「現在の設定を維持」を意味します — 両方を変更しない場合は値初期化構造体を返します（`return {};`）。 新しい poll ファイルディスクリプタを設定するには、その値を返します（0より大きい必要があります）。既存の poll ファイルディスクリプタをクリアするには、`poll_fd` に `-1` を返します。 理由が `VEF_WAKEUP_DISABLE` の場合、戻り値は無視されます。 ### スレッド名と制御変数 記述子の2つのフィールドが命名を制御します： * `suffix` — スレッド名サフィックス。サーバーは拡張機能名を前置し、`my_ext/monitor` のようなスレッド名を生成します。 * `var_name` — オプション。NULL でない場合、サーバーはこの名前を制御システム変数として登録します。NULL の場合、サーバーはデフォルトパターン `{suffix}_enabled` を使用します。 制御変数はサーバー登録のシステム変数です。ワーカーを有効化するには `SET GLOBAL {suffix}_enabled = ON`、無効化するには `OFF` に設定します。 ### 完全な例 単一の定期ワーカーを備えた最小限の拡張機能で、タイマー刻みごとにハートビートカウンターをインクリメントします。 ```cpp theme={null} #include #include #include static std::atomic g_heartbeat{0}; static vef_next_wakeup_t heartbeat_work(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg) { switch (reason) { case VEF_WAKEUP_ENABLE: return {1000, 0}; // tick every 1000 ms, no poll fd case VEF_WAKEUP_PERIODIC: g_heartbeat.fetch_add(1, std::memory_order_relaxed); return {}; // keep current sleep_ms and poll_fd case VEF_WAKEUP_POLL_FD: return {}; // not used in this example case VEF_WAKEUP_DISABLE: return {}; // ignored } return {}; } static vsql::preview_thread_worker::ThreadWorkerCapability<&heartbeat_work> g_worker{"heartbeat"}; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_worker)) ``` この拡張機能をインストールし（`vsql_allow_preview_extensions = ON` が設定されている場合）、サーバーは `heartbeat_enabled` システム変数を登録します。ワーカーを有効化するには： ```sql theme={null} SET GLOBAL heartbeat_enabled = ON; ``` ## SQL クエリ sql\_query 機能（`vsql::preview::sql_query`）は、バックグラウンドスレッドから SQL 文を実行できるようにします。クエリは機能の vtable を介してサーバー内部で実行され、拡張機能は MySQL クライアントライブラリをリンクしません。 機能名 `VEF_PREVIEW_SQL_QUERY_NAME` は `"vsql::preview::sql_query"` です。 SQL セッションは、スレッドワーカーのコールバックからそのコールバックの `vef_thread_handle_t *` を使用して開く必要があります。`open()` は VDF または任意の拡張機能作成スレッドから有効ではありません — これはワーカーセッションコンテキストを必要とします。 ### 機能の宣言 ヘッダーを含め、ファイルスコープで `SqlQueryCapability` を宣言し、`.with()` に渡します。通常、`ThreadWorkerCapability` と共に登録されます。セッションはワーカーのコールバックから開かれるためです： ```cpp theme={null} #include #include #include static vsql::preview_sql_query::SqlQueryCapability g_sql; static vef_next_wakeup_t my_work(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg) { auto session = g_sql.open(thread); if (!session) return {}; // ... return {}; } static vsql::preview_thread_worker::ThreadWorkerCapability<&my_work> g_worker{"sql_demo"}; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_worker) .with(g_sql)) ``` `g_sql.open(handle)` は `Session` を返します。使用前に `operator bool` でチェックしてください。無効な `Session` は機能 vtable がバインドされていないか、サーバーがセッションを割り当てられなかったことを示します。`Session` はムーブオンリーで、破棄時に自動的に閉じられます。 ### クエリの実行 `Session` は `session.sql(sv)` で `SqlQuery` を生成します。クエリは2つのモードで実行できます： * `execute()` — 文を実行し、完全な結果セットを `Result` にバッファリングします。`next()` を呼び出して行をイテレートします。 * `for_each(fn)` — 文を実行し、行が生成されるたびに `fn` を1回呼び出します。バッファリングしません。返される `Result` には診断情報のみ（行なし）が含まれます。 両方とも `Result` を返します。非 NULL の `Result` は文が成功したことを意味しません — `has_error()` を呼び出して確認してください。 バッファリング（`execute`）： ```cpp theme={null} auto result = session.sql("SELECT id, name FROM t").execute(); if (result.has_error()) { // result.error().message holds the server error string. return {}; } while (result.next()) { long long id = result.column_int(0); std::string_view name = result.column_str(1); // ... } ``` `column_str()` は `string_view` を返します。これは次の `next()` 呼び出しまたは `Result` 破棄まで有効です。より長い寿命が必要な場合はコピーしてください。`data() == nullptr` の `string_view` は SQL NULL を示します。 ストリーミング（`for_each`）： ```cpp theme={null} auto status = session.sql("SELECT 1").for_each( [](const auto &row) { // row.column_int(0), row.column_str(1), etc. }); if (status.has_error()) { // status.error().message } ``` コールバックに渡される `Row` はコールバックの実行中のみ有効です — 行間で参照を保持しないでください。`for_each` が返す `Result` はバッファリングされた行を持たず、`next()` はデータを返しません。`has_error()`、`error()`、`warning_count()`、`warning(i)` のみに使用してください。 ### 診断 `execute()` および `for_each()` は返される `Result` を介して診断情報を返します。診断は1つの `Diag` です： ```cpp theme={null} struct Diag { uint32_t errno_; vef_sql_diag_severity_t severity; // NOTE | WARNING | ERROR std::string_view sqlstate; // 5-char SQLSTATE std::string_view message; // may be empty }; ``` | フィールド | 意味 | | ---------- | ---------------------------------------------------------------- | | `errno_` | MySQL エラーナンバー。エラーがない場合に返されるデフォルト構築された `Diag` では `0`。 | | `severity` | `VEF_SQL_DIAG_NOTE`、`VEF_SQL_DIAG_WARNING`、`VEF_SQL_DIAG_ERROR`。 | | `sqlstate` | 5文字の SQLSTATE。 | | `message` | サーバー提供の診断メッセージ；空の場合あり。 | `Result` は以下を公開します： ```cpp theme={null} bool Result::has_error() const; Diag Result::error() const; unsigned int Result::warning_count() const; Diag Result::warning(unsigned int i) const; ``` `error()` は文が成功した場合、デフォルト構築された `Diag`（`errno_ == 0`）を返します。`warning(i)` は `i >= warning_count()` の場合、デフォルト構築された `Diag` を返します。 `sqlstate` および `message` のビューは `Result` が所有するストレージを指しており、`Result` が破棄されると無効になります — `Result` の生存期間を超えて保持する必要がある場合はコピーしてください。 ### 完全な例 タイマー刻みごとに1つのバッファリングクエリと1つのストリーミングクエリを実行し、両方の診断をログ出力するワーカー： ```cpp theme={null} #include #include #include static vsql::preview_sql_query::SqlQueryCapability g_sql; static vef_next_wakeup_t sql_demo_work(vef_wakeup_reason_t reason, struct vef_thread_handle_t *thread, void *arg) { if (reason == VEF_WAKEUP_ENABLE) return {5000, 0}; if (reason != VEF_WAKEUP_PERIODIC) return {}; auto session = g_sql.open(thread); if (!session) return {}; // Buffered: read a small result set. auto rs = session.sql("SELECT id, name FROM mydb.t LIMIT 10").execute(); if (rs.has_error()) { auto e = rs.error(); // Log e.errno_, e.sqlstate, e.message somewhere extension-owned. } else { while (rs.next()) { long long id = rs.column_int(0); std::string_view name = rs.column_str(1); (void)id; (void)name; } } // Streaming: process rows without buffering. auto status = session.sql("SELECT v FROM mydb.t").for_each( [](const auto &row) { long long v = row.column_int(0); (void)v; }); for (unsigned i = 0; i < status.warning_count(); ++i) { auto w = status.warning(i); (void)w; } return {}; } static vsql::preview_thread_worker::ThreadWorkerCapability<&sql_demo_work> g_worker{"sql_demo"}; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_worker) .with(g_sql)) ```

カラムストレージ

カラムストレージは、拡張機能が InnoDB に直接カスタム型のバイナリディスクレイアウトを登録できるようにします。これにより、VARBINARYペイロード経由で型のバイトをルーティングするのではなく、カスタム型のディスク形状を直接表現できます。例えば、専用ページに格納される必要のある圧縮浮動小数点配列など、VARBINARYが表現できないディスク形状が必要な場合に使用します。これは新しいストレージレイアウトを可能にする機能追加であり、既存のレイアウトのチューニングスイッチではありません。 カラムストレージはプレビューABIです — 開発中であり、リリース間で変更される可能性があります。現在、行レベルの永続化のみをカバーしており、カスタムストアードカラムのインデックスはまだ利用できません。 ### 機能の宣言 2つのプレビュー機能が連携して動作します： * `vsql::preview::storage` — InnoDB ストレージインフラストラクチャ（ミニトランザクション、セグメント、ページ）へのアクセスを提供します。ファイルスコープで `StorageCapability` を宣言します。 * `vsql::preview::column_store` — 拡張機能のカスタム型の1つに、1つのストレージ実装をバインドします。`make_column_store(TYPE).…build()` を使用してファイルスコープで `ColumnStoreCapability` を宣言します。 両方を `make_extension()` の `.with()` に渡す必要があります： ```cpp theme={null} #include #include #include namespace storage = vsql::preview_storage; using vsql::preview_storage_builder::ColumnStoreCapability; using vsql::preview_storage_builder::make_column_store; using vsql::preview_storage_builder::StorageCapability; struct MyCtx { storage::Space::Ref space = 0; storage::Segment::PageRef root_page = storage::Page::INVALID_REF; }; static auto STORAGE = StorageCapability{}; static constexpr auto kMyStorage = make_column_store(MY_TYPE) .create<&MyStorage::create>() .drop<&MyStorage::drop>() .load<&MyStorage::load>() .insert<&MyStorage::insert>() .select<&MyStorage::select>() .mark_delete<&MyStorage::mark_delete>() .purge<&MyStorage::purge>() .build(); static auto COLUMN_STORE = ColumnStoreCapability().column_store(kMyStorage); using namespace vsql; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(STORAGE) .with(COLUMN_STORE) .type(MY_TYPE)) ``` `make_column_store(MY_TYPE)` は実装を同じ拡張機能で登録された1つのカスタム型に紐付けます。`build()` 時に7つのスロットが必要です。各スロットは InnoDB が通常動作中に到達するカラムライフサイクルの異なるポイントに対応します。 ### 7つのストレージ関数 すべての関数は `storage::Column::StorageCtx*` を受け取ります。`user()` アクセサは拡張機能のカラムごとの状態を返し、`arena()` は補助オブジェクトのサーバー管理割り当てを提供します。すべての関数は成功時に `false` を返し、エラー時に `true` を返し、`error_msg`（容量 `error_msg_len`）にメッセージを書き込みます。 ```cpp theme={null} // CREATE TABLE / ALTER TABLE ADD COLUMN. // col_len is the type's persisted length. Reserve segments here and store // space + root_page in ctx->user() so DML functions can reach them. bool create(storage::Column::StorageCtx*, storage::Space::Ref, storage::Segment::TrxRef, uint32_t col_len, char* error_msg, uint32_t error_msg_len); // DROP TABLE / ALTER TABLE DROP COLUMN. // Release any segments reserved in create(). Arena memory is freed by the // server after this call returns. bool drop(storage::Column::StorageCtx*, storage::Segment::TrxRef, char* error_msg, uint32_t error_msg_len); // Called when the server reattaches to existing storage (e.g. after restart). // Recover space and root_page from the StorageRef set in create(). bool load(storage::Column::StorageCtx*, storage::Column::StorageRef, char* error_msg, uint32_t error_msg_len); // INSERT. col_data is the encoded value; rowid_prefix identifies the owning // row. Write into your storage layout and return a Column::Ref the server // stores in the row payload in place of the value bytes. bool insert(storage::Column::StorageCtx*, storage::MtrCtx::Ref, storage::Segment::TrxRef, storage::Column::Data col_data, storage::Column::Data rowid_prefix, storage::Column::Ref* col_ref, char* error_msg, uint32_t error_msg_len); // SELECT. Given the Column::Ref produced by insert, populate col_data and // rowid_prefix, and report the writing transaction and delete-mark status. bool select(storage::Column::StorageCtx*, storage::MtrCtx::Ref, storage::Column::Ref, storage::Column::Data* col_data, storage::Column::Data* rowid_prefix, storage::Segment::TrxRef*, bool* delete_marked, char* error_msg, uint32_t error_msg_len); // DELETE (in-transaction). Set or clear the delete-mark flag. The actual // bytes must remain readable until purge() runs. bool mark_delete(storage::Column::StorageCtx*, storage::MtrCtx::Ref, storage::Segment::TrxRef, storage::Column::Ref, bool delete_mark, char* error_msg, uint32_t error_msg_len); // InnoDB purge. Reclaim storage for entries whose deleting transaction is // no longer visible to any active snapshot. bool purge(storage::Column::StorageCtx*, storage::MtrCtx::Ref, storage::Segment::TrxRef, storage::Column::Ref, char* error_msg, uint32_t error_msg_len); ``` `mark_delete` と `purge` は区別されます。InnoDB MVCC では、削除された行は purge が実行されるまで古いスナップショットで読み取り可能でなければなりません。 ### カラムごとのコンテキストとアリーナ C++ SDK は `create` または `load` を呼び出す前に `MyCtx` をデフォルト構築します — 関数が実行される時点で `ctx->user()` には既に値が設定されています。`MyCtx` はデフォルト構築可能でなければなりません。C++ SDK は引数なしで `T()` を呼び出します。 `ctx->user()` を直接使用して状態を初期化します。`ctx->arena().construct()` を呼び出さないでください — これは不要なインスタンスを割り当てますが、`ctx->user()` はその領域を指していません。 ```cpp theme={null} bool MyStorage::create(storage::Column::StorageCtx* ctx, storage::Space::Ref space, storage::Segment::TrxRef trx, uint32_t col_len, char* error_msg, uint32_t error_msg_len) { storage::Segment::PageRef root; if (storage::Segment::create(space, 1, trx, root) != storage::Error::SUCCESS) { snprintf(error_msg, error_msg_len, "%s", storage::last_error().data()); return true; } ctx->user()->space = space; ctx->user()->root_page = root; // Encode space and root into StorageRef so load() can recover both. ctx->set_ref((static_cast(space) << 32) | static_cast(root)); return false; } ``` `load` も同様のパターンです — `ctx->user()` には既に値が設定されており、`storage_ref` は `create` で `ctx->set_ref()` が格納したパックされた値を保持します： ```cpp theme={null} bool MyStorage::load(storage::Column::StorageCtx* ctx, storage::Column::StorageRef storage_ref, char* error_msg, uint32_t error_msg_len) { ctx->user()->space = static_cast(storage_ref >> 32); ctx->user()->root_page = static_cast(storage_ref & 0xFFFFFFFF); ctx->set_ref(storage_ref); return false; } ``` `ctx->arena()` は `MyCtx` に直接埋め込むことができないほど大きいか動的な補助オブジェクトを割り当てる場合にのみ使用します。C++ SDK はアリーナを破棄し（`~MyCtx()` を呼び出し）、`drop` が成功するかどうかに関係なく、`drop` が返した後自動的に破棄します。 ### InnoDB アクセスユーティリティ InnoDB プリミティブには `` を含めます。すべてのページ読み書きはミニトランザクション内で行われます： ```cpp theme={null} storage::MtrCtx mtr; storage::MtrCtx::Ref mtr_ref = mtr.start(); if (mtr_ref == nullptr) { /* OOM — handle error */ return true; } // ... page operations ... mtr.commit(); ``` ミニトランザクションのコミットはページラッチを解放し、変更を永続化する redo ログレコードを書き込みます。 **セグメント** は `create` 時に予約されます — セグメントのセットアップパターンについては、上記の「カラムごとのコンテキスト」の `create` および `load` 例を参照してください。DML操作中、ルートページからセグメント参照を取得して新しいページを割り当てます： ```cpp theme={null} storage::Page root; root.load(ctx->user()->space, ctx->user()->root_page, storage::Page::Latch::EXCLUSIVE, mtr_ref); storage::Segment::Ref seg = storage::Segment::get_header(root, 0); storage::Page data_page; data_page.load_new(seg, mtr_ref); // allocates a fresh page ``` **ページ** は共有ラッチで読み取り、排他ラッチで書き込みます。InnoDB が変更をログに記録するため、`mtr_ref` を書き込み呼び出しに渡します： ```cpp theme={null} storage::Page page; // Read page.load(ctx->user()->space, page_num, storage::Page::Latch::SHARED, mtr_ref); uint32_t v = page.read_integer_4(storage::Page::HEADER_SIZE + offset); // Write page.load(ctx->user()->space, page_num, storage::Page::Latch::EXCLUSIVE, mtr_ref); page.write_integer_4(storage::Page::HEADER_SIZE + offset, v, mtr_ref); ``` ページレイアウト定数: | 定数 | 値 | 説明 | | -------------------------------- | ------- | ------------------------------------------- | | `storage::Page::HEADER_SIZE` | `38` | 拡張データはこのオフセットから開始されます。 | | `storage::Page::TRAILER_SIZE` | `8` | `page_size - TRAILER_SIZE` を超えて書き込まないでください。 | | `storage::Page::get_size(space)` | runtime | 16384 をハードコードする代わりに使用してください。 | ヘッダーまたはトレーラー領域内での読み取りまたは書き込みはページを破損させます — InnoDB はこれらのバイト範囲を自身の管理およびチェックサムに使用しています。 ## ステートメントイベント statement event 機能（`vsql::preview::statement_event`）は、各クエリの実行完了後に拡張機能提供のハンドラを実行します。サーバーはハンドラをクエリ自身のスレッドで同期的に呼び出し、実行メタデータ — クエリテキスト、タイミング、行数、接続元の識別情報、オプティマイザ品質インジケータ — を渡します。スロークエリのログ記録、監査、メトリクス収集に使用します。 機能名 `VEF_PREVIEW_STATEMENT_EVENT_NAME` は `"vsql::preview::statement_event"` です。 ### 機能の宣言 発火フェーズとハンドラ関数でインスタンス化した `StatementEventCapability` をファイルスコープで宣言し、`.with()` に渡します： ```cpp theme={null} #include #include namespace se = vsql::preview_statement_event; static void on_statement(const se::StatementEventArgs &args, se::StatementEventResult &result) { // inspect args; optionally write an advisory message via result } static se::StatementEventCapability g_statement_event; VEF_GENERATE_ENTRY_POINTS( make_extension() .with(g_statement_event)) ``` 最初のテンプレート引数は発火フェーズで、`vef_statement_event_phase_t` 値です。`VEF_STATEMENT_EVENT_POSTEXECUTE` はクエリの実行完了後に、成功または失敗にかかわらず発火し、このバージョンで実装されている唯一のフェーズです。その他の `vef_statement_event_phase_t` 値は予約されており、そのいずれかに対してハンドラを宣言すると、サーバーは `INSTALL EXTENSION` を拒否します。 ### ハンドラ引数 `StatementEventArgs` は完了したクエリの読み取り専用ビューです。POSTEXECUTE フェーズではすべてのフィールドに値が設定されています。主なアクセサ： | アクセサ | 意味 | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `query()` | クエリテキスト、`string_view` として。サーバーが文の書き換え形式を持つ場合、これはその形式です — 一般ログ、スローログ、バイナリログが記録するのと同じ、難読化（伏字化）されたテキストです。 | | `query_time_secs()` | 実行時間（ウォールクロック時間、秒）。 | | `lock_time_secs()` | ロック待機に費やした時間（秒）。 | | `rows_sent()`, `rows_examined()`, `rows_affected()` | 行カウンター。 | | `user()`, `client_ip()`, `connection_id()` | 接続元の識別情報。 | | `schema()` | デフォルトスキーマ、選択されていない場合は `NULL`。 | | `status()` | 成功時は `0`、それ以外は MySQL エラーコード。 | | `digest_text()` | 類似クエリをグループ化するための正規化されたクエリ形式。 | | `no_index_used()` | クエリが使用可能なインデックスなしで実行された場合 `true`。 | `query()` は存在する場合サーバーの書き換え形式を返すため、認証情報を含む文はシークレットが平文ではなく難読化された状態で到着し、一般ログ、スローログ、バイナリログが既にそれらを難読化（伏字化）する方法と一致します：`SET PASSWORD`、`CREATE`/`ALTER USER ... IDENTIFIED BY`、`CHANGE REPLICATION SOURCE ... SOURCE_PASSWORD`、`CREATE SERVER ... OPTIONS(PASSWORD ...)`。書き換えルールのない文はそのまま配信されます。 `query()`、`sqlstate()`、`error_message()` などの文字列アクセサは、ハンドラ呼び出しの実行中のみ有効なストレージを指しています — ハンドラが返った後にそれらが必要な場合はバイトをコピーしてください。 `StatementEventResult::error_msg(fmt, ...)` は printf 形式のメッセージを書き込みます。POSTEXECUTE フェーズでは、メッセージは参考情報（アドバイザリ）であり、サーバーはログに記録しますが、クライアントには伝播しません。 ### 完全な例 サーバーに同梱される [`vsql_slow_query_log`](https://github.com/villagesql/villagesql-server/tree/main/villagesql/test-extensions/vsql-slow-query-log) テスト拡張機能の簡略化された形式です。実行時間がしきい値を超える各クエリをログに記録し、statement event 機能を[システム変数](#system-variables)と組み合わせて実行時設定を行います： ```cpp theme={null} #include #include #include #include #include #include #include #include using namespace vsql; namespace sv = vsql::preview_sys_var; namespace se = vsql::preview_statement_event; static bool g_enabled; static long long g_threshold_ms; static char *g_log_filename; static std::mutex g_log_mutex; static void slow_query_hook(const se::StatementEventArgs &args, se::StatementEventResult &result) { if (!g_enabled) return; if (args.query_time_secs() * 1000.0 < static_cast(g_threshold_ms)) return; time_t now = static_cast(args.query_start_utime() / 1000000); char ts[32]; struct tm tm_utc; gmtime_r(&now, &tm_utc); strftime(ts, sizeof(ts), "%Y-%m-%dT%H:%M:%SZ", &tm_utc); std::lock_guard lock(g_log_mutex); FILE *f = fopen(g_log_filename, "a"); if (f == nullptr) { result.error_msg("failed to open '%s': %s", g_log_filename, strerror(errno)); return; } fprintf(f, "# Time: %s\n", ts); fprintf(f, "# User@Host: %s @ %s Id: %lu\n", args.user() ? args.user() : "", args.client_ip() ? args.client_ip() : "", args.connection_id()); fprintf(f, "# Schema: %s Query_time: %.6f Lock_time: %.6f" " Rows_sent: %llu Rows_examined: %llu\n", args.schema() ? args.schema() : "", args.query_time_secs(), args.lock_time_secs(), (unsigned long long)args.rows_sent(), (unsigned long long)args.rows_examined()); fprintf(f, "SET timestamp=%llu;\n", (unsigned long long)now); auto q = args.query(); fprintf(f, "%.*s;\n", (int)q.size(), q.data()); fclose(f); } static auto SYS_VARS = sv::make_capability({ sv::make_bool("enabled", "Enable the slow query log", &g_enabled, false), sv::make_int("threshold_ms", "Minimum execution time to log, in ms", &g_threshold_ms, 1000, 0, 3600000), sv::make_str("log_file", "Path to the slow query log file", &g_log_filename, "/tmp/vsql_slow_query.log")}); static se::StatementEventCapability STATEMENT_EVENT; VEF_GENERATE_ENTRY_POINTS( make_extension().with(SYS_VARS).with(STATEMENT_EVENT)) ``` #### SQL からの有効化 プレビュー層を有効化した上で（[プレビュー層の有効化](#enabling-the-preview-tier)を参照）、拡張機能をインストールし、そのシステム変数を通じて設定します： ```sql theme={null} INSTALL EXTENSION vsql_slow_query_log; SET GLOBAL vsql_slow_query_log.enabled = ON; SET GLOBAL vsql_slow_query_log.threshold_ms = 500; ``` しきい値より遅い各クエリは、設定されたログファイルに追記されます： ``` # Time: 2026-06-22T22:53:44Z # User@Host: root @ Id: 27 # Schema: Query_time: 0.605084 Lock_time: 0.000000 Rows_sent: 1 Rows_examined: 1 SET timestamp=1782168824; SELECT SLEEP(0.6); ```