プレビュー機能 - VillageSQL Server for MySQL

プレビュー機能は、APIが最終化される前に拡張機能に公開されるサーバー機能です。プレビュー機能を宣言する拡張機能は、vsql_allow_preview_extensions = ON が設定されている場合にのみインストールできます（プレビュー層の有効化を参照）—プレビュー機能を使用しない拡張機能は、この設定に関係なく通常通りインストールされます。

プレビュー機能APIは安定していません。プレビュー機能に依存して構築された拡張機能は、サーバーのアップデート後にロードに失敗する可能性があります。機能が安定化すると、そのヘッダーはバージョン化された安定版 C++ SDK パスに移動されます。

プレビュー層の有効化

プレビュー機能を使用する拡張機能をインストールする前に、SET PERSIST を使用して vsql_allow_preview_extensions = ON を設定します：

SET PERSIST vsql_allow_preview_extensions = ON;

SET GLOBAL はこの変数に対して拒否されます — サーバーは設定を再起動後に保持するために SET PERSIST を要求します。プレビュー機能を持つ拡張機能は起動時にロードされるため、サーバーが起動する時点でこの変数が ON である必要があります。 mysqld を直接起動する場合（例：サーバーを初めて起動するインストールスクリプトから）、コマンドライン引数でフラグを渡してください — mysqld-auto.cnf がまだ存在しないため、永続化された値を保持できません：

mysqld --vsql_allow_preview_extensions=ON

無効化するには：

SET PERSIST vsql_allow_preview_extensions = OFF;

プレビュー機能を使用する拡張機能が現在インストールされている場合、失敗します。まずそれらの拡張機能をアンインストールし、その後設定をオフにします。

機能インデックス

機能	ヘッダー	状態
`vsql::preview::column_store`	`<villagesql/preview/storage_builder.h>`	プレビュー
`vsql::preview::keyring`	`<villagesql/preview/keyring.h>`	プレビュー
`vsql::preview::sql_query`	`<villagesql/preview/sql_query.h>`	プレビュー
`vsql::preview::statement_event`	`<villagesql/preview/statement_event.h>`	プレビュー
`vsql::preview::status_var`	`<villagesql/preview/status_var.h>`	プレビュー
`vsql::preview::storage`	`<villagesql/preview/storage_builder.h>`	プレビュー
`vsql::preview::sys_var`	`<villagesql/preview/sys_var.h>`	プレビュー
`vsql::preview::thread_worker`	`<villagesql/preview/thread_worker.h>`	プレビュー

登録パターン

プレビュー機能を使用するには、ファイルスコープで機能オブジェクトを値として宣言し、make_extension() 内の .with() に参照で渡します。サーバーは登録時にオブジェクトの abi ポインタを設定します：

#include <villagesql/preview/keyring.h>
#include <villagesql/vsql.h>

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 '<Type>' was declared but never passed to .with(); every CapabilityBase-derived static must be registered via .with(cap) in the extension builder
同じインスタンスを .with() に複数回渡した場合： capability '<Type>' 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 '<name>': vef_register returned an error: <message above> として表示されます。

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() に渡します：

#include <villagesql/preview/keyring.h>
#include <villagesql/vsql.h>

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 を返します — 別の利用可能性チェックで処理をガードする代わりに、各呼び出しでステータスを確認してください。

読み書き

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 を返します。構造化バインディングでバインドします：

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。

#include <villagesql/preview/keyring.h>
#include <villagesql/vsql.h>

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) から得られる記述子のブレースリストを渡します。テンプレートはブレースリストからカウントを推測するため、明示的なサイズは必要ありません。

完全な例

#include <villagesql/preview/status_var.h>
#include <villagesql/vsql.h>

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 後、変数は拡張機能名をプレフィックスとして表示されます：

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`

完全な例

#include <villagesql/preview/sys_var.h>
#include <villagesql/vsql.h>

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 後、変数には拡張機能名をコンポーネントプレフィックスとしてアクセスできます：

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 を返します。

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() に渡します：

#include <villagesql/preview/thread_worker.h>
#include <villagesql/vsql.h>

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 名をオーバーライドします。

作業関数シグネチャ

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 戻り値

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 に設定します。

完全な例

単一の定期ワーカーを備えた最小限の拡張機能で、タイマー刻みごとにハートビートカウンターをインクリメントします。

#include <villagesql/preview/thread_worker.h>
#include <villagesql/vsql.h>

#include <atomic>

static std::atomic<unsigned long long> 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 システム変数を登録します。ワーカーを有効化するには：

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 と共に登録されます。セッションはワーカーのコールバックから開かれるためです：

#include <villagesql/preview/sql_query.h>
#include <villagesql/preview/thread_worker.h>
#include <villagesql/vsql.h>

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）：

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）：

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 です：

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 は以下を公開します：

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つのストリーミングクエリを実行し、両方の診断をログ出力するワーカー：

#include <villagesql/preview/sql_query.h>
#include <villagesql/preview/thread_worker.h>
#include <villagesql/vsql.h>

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<Ctx>(TYPE).…build() を使用してファイルスコープで ColumnStoreCapability を宣言します。

両方を make_extension() の .with() に渡す必要があります：

#include <villagesql/preview/storage_builder.h>
#include <villagesql/preview/storage_api.h>
#include <villagesql/vsql.h>

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<MyCtx>(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<MyCtx>(MY_TYPE) は実装を同じ拡張機能で登録された1つのカスタム型に紐付けます。build() 時に7つのスロットが必要です。各スロットは InnoDB が通常動作中に到達するカラムライフサイクルの異なるポイントに対応します。

7つのストレージ関数

すべての関数は storage::Column::StorageCtx<MyCtx>* を受け取ります。user() アクセサは拡張機能のカラムごとの状態を返し、arena() は補助オブジェクトのサーバー管理割り当てを提供します。すべての関数は成功時に false を返し、エラー時に true を返し、error_msg（容量 error_msg_len）にメッセージを書き込みます。

// 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<MyCtx>*, 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<MyCtx>*, 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<MyCtx>*, 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<MyCtx>*, 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<MyCtx>*, 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<MyCtx>*, 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<MyCtx>*, 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<MyCtx>() を呼び出さないでください — これは不要なインスタンスを割り当てますが、ctx->user() はその領域を指していません。

bool MyStorage::create(storage::Column::StorageCtx<MyCtx>* 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<storage::Column::StorageRef>(space) << 32) |
               static_cast<storage::Column::StorageRef>(root));
  return false;
}

load も同様のパターンです — ctx->user() には既に値が設定されており、storage_ref は create で ctx->set_ref() が格納したパックされた値を保持します：

bool MyStorage::load(storage::Column::StorageCtx<MyCtx>* ctx,
                     storage::Column::StorageRef storage_ref,
                     char* error_msg, uint32_t error_msg_len) {
  ctx->user()->space =
      static_cast<storage::Space::Ref>(storage_ref >> 32);
  ctx->user()->root_page =
      static_cast<storage::Segment::PageRef>(storage_ref & 0xFFFFFFFF);
  ctx->set_ref(storage_ref);
  return false;
}

ctx->arena() は MyCtx に直接埋め込むことができないほど大きいか動的な補助オブジェクトを割り当てる場合にのみ使用します。C++ SDK はアリーナを破棄し（~MyCtx() を呼び出し）、drop が成功するかどうかに関係なく、drop が返した後自動的に破棄します。

InnoDB アクセスユーティリティ

InnoDB プリミティブには <villagesql/preview/storage_api.h> を含めます。すべてのページ読み書きはミニトランザクション内で行われます：

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操作中、ルートページからセグメント参照を取得して新しいページを割り当てます：

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 を書き込み呼び出しに渡します：

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() に渡します：

#include <villagesql/preview/statement_event.h>
#include <villagesql/vsql.h>

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<VEF_STATEMENT_EVENT_POSTEXECUTE,
                                    &on_statement>
    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 テスト拡張機能の簡略化された形式です。実行時間がしきい値を超える各クエリをログに記録し、statement event 機能をシステム変数と組み合わせて実行時設定を行います：

#include <cerrno>
#include <cstdio>
#include <cstring>
#include <ctime>
#include <mutex>

#include <villagesql/preview/statement_event.h>
#include <villagesql/preview/sys_var.h>
#include <villagesql/vsql.h>

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<double>(g_threshold_ms))
    return;

  time_t now = static_cast<time_t>(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<std::mutex> 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<VEF_STATEMENT_EVENT_POSTEXECUTE,
                                    &slow_query_hook>
    STATEMENT_EVENT;

VEF_GENERATE_ENTRY_POINTS(
    make_extension().with(SYS_VARS).with(STATEMENT_EVENT))

SQL からの有効化

プレビュー層を有効化した上で（プレビュー層の有効化を参照）、拡張機能をインストールし、そのシステム変数を通じて設定します：

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);

​プレビュー層の有効化

​機能インデックス

​登録パターン

​Keyring アクセス

​ステータス値

​機能の宣言

​読み書き

​完全な例

​ステータス変数

​完全な例

​SQL からのアクセス

​システム変数

​完全な例

​SQL からのアクセス

​拡張機能コードからの読み書き

​スレッドワーカー

​機能の宣言

​作業関数シグネチャ

​Wakeup ライフサイクル

​Wakeup 戻り値

​スレッド名と制御変数

​完全な例

​SQL クエリ

​機能の宣言

​クエリの実行

​診断

​完全な例

​カラムストレージ

​機能の宣言

​7つのストレージ関数

​カラムごとのコンテキストとアリーナ

​InnoDB アクセスユーティリティ

​ステートメントイベント

​機能の宣言

​ハンドラ引数

​完全な例

​SQL からの有効化

プレビュー層の有効化

機能インデックス

登録パターン

Keyring アクセス

ステータス値

機能の宣言

読み書き

完全な例

ステータス変数

完全な例

SQL からのアクセス

システム変数

完全な例

SQL からのアクセス

拡張機能コードからの読み書き

スレッドワーカー

機能の宣言

作業関数シグネチャ

Wakeup ライフサイクル

Wakeup 戻り値

スレッド名と制御変数

完全な例

SQL クエリ

機能の宣言

クエリの実行

診断

完全な例

カラムストレージ

機能の宣言

7つのストレージ関数

カラムごとのコンテキストとアリーナ

InnoDB アクセスユーティリティ

ステートメントイベント

機能の宣言

ハンドラ引数

完全な例

SQL からの有効化