メインコンテンツへスキップ
このページの機能はプレビュー段階です。API は安定しておらず、これらの機能を宣言する拡張機能は、vsql_allow_preview_extensions = ON が設定されている場合にのみインストールできます。プレビュー層の有効化と機能の登録方法については、プレビュー機能を参照してください。

Keyring アクセス

keyring 機能(vsql::preview::keyring)は、MySQL keyring コンポーネントに格納されたシークレットを拡張機能が読み書きできるようにします。APIキー、暗号化キー、またはSQLテーブルに保存したくないその他のシークレットに使用します。 機能名 VEF_PREVIEW_KEYRING_NAME は "vsql::preview::keyring" です。 keyring コンポーネント(たとえば component_keyring_file)は、Keyring Component Installation に記載されているとおり、コンポーネントマニフェストとその設定ファイルを通じてサーバー起動時にロードされている必要があります。INSTALL COMPONENT ではそれを利用可能にできません。ロードされていない場合、操作は KeyringCapability::Status::UNAVAILABLE を返します。

ステータス値

KeyringCapability::Status は read()(ReadResult 内)および write() から返されるスコープ付き列挙型です:

機能の宣言

ヘッダーを含め、ファイルスコープで機能オブジェクトを宣言し、.with() に渡します:
g_keyring オブジェクトはロード時にサーバーによって初期化されます。keyring コンポーネントがインストールされていない場合、read() および write() は実行時に Status::UNAVAILABLE を返します — 別の利用可能性チェックで処理をガードする代わりに、各呼び出しでステータスを確認してください。

読み書き

data_id はキー識別子です。auth_id は所有ユーザーです — 内部キー(特定のユーザーに関連付けられていない)を読み書きするには空文字列(または read では省略、デフォルトは {})を渡します。 read は値で ReadResult を返します。構造化バインディングでバインドします:
Status::OK 以外のステータスの場合、value は空です。 write は直接 Status を返し、data を data_id / auth_id で格納します。component_keyring_file では、既存のキーへの書き込みは Status::ERROR を返します。

完全な例

これはサーバーの villagesql/test-extensions/ ツリーにある vsql_keyring_reader テスト拡張機能の簡略化されたバージョンです。2つの VDF を登録します:keyring_read および keyring_store。

MySQL サービス

mysql_services 機能(vsql::preview::mysql_services)は、拡張機能が MySQL レジストリサービスを利用できるようにします — MySQL コンポーネントが利用するのと同じサービスで、インストールされたコンポーネントまたはサーバーコアによって提供されます。拡張機能は必要なすべてのサービスを1か所で宣言します。サーバーは拡張機能のロード時に各サービスを取得し、拡張機能のアンロード時に解放します。 機能名 VEF_PREVIEW_MYSQL_SERVICES_NAME は "vsql::preview::mysql_services" です。 サーバーの機構に専用の VEF 機能がない場合にこれを使用します。セッション属性と keyring 自身のコンポーネントサービスは、どちらもこの方法で利用できます。サポートされるのは利用のみです。拡張機能自身の実装をレジストリに登録することは今後の作業として計画されており、この機能には含まれません。

機能の宣言

ファイルスコープで MysqlServices オブジェクトを1つ宣言し、利用する各サービスを VSQL_REQUIRE_SERVICE で指定し、そのオブジェクトを .with() に渡します。各サービスについて MySQL 自身のヘッダーを含めてください — サービスの型とメソッドはそのヘッダーで宣言されています:
VSQL_REQUIRE_SERVICE(services, name, var) は、サーバーが取得したサービスを書き込む参照 var を宣言し、name を services に登録します。var は自動的に static として宣言されます。MysqlServices オブジェクトも static である必要があり、手動で宣言する参照も同様です。サーバーはロード時にそれらを介して書き込むため、それらは拡張機能より長く存続する必要があります。

特定の実装の指定

VSQL_REQUIRE_SERVICE は name を2回使用します — C++ の SERVICE_TYPE(name) として、およびサーバーがレジストリで検索する文字列として。この修飾なしの名前では、サーバーはサービスのデフォルト実装を取得します。 代わりに1つの実装を指定するには、修飾されたレジストリ名 — MySQL の PROVIDES_SERVICE(component, service) が生成する service.component の形式 — を使用します。以下は、デフォルトではなく component_keyring_file コンポーネントの keyring リーダーを要求します:
修飾された名前は修飾なしの名前と同じ方法で取得されるため、通常のルールが適用されます。その実装が登録されていない場合、拡張機能は別の実装にフォールバックするのではなくインストールに失敗します。

MySQL のヘッダーに対するビルド

サービス定義は VEF ではなく MySQL のコンポーネントフレームワークに属しており、サーバーはそれらをインストールしません。そのため mysql/components/services/*.h は、拡張機能 SDK にも、make install が構築するもの(リリース tarball や Docker イメージを含む)にも存在しません。サービスを利用する拡張機能は、VillageSQL サーバーのソースツリーに対してビルドします: ツリー内のテスト拡張機能は、vsql_add_test_extension() の MYSQL_HEADERS フラグから両方を取得します。このフラグはそれらを MYSQL_INCLUDE_DIR および MYSQL_GENERATED_INCLUDE_DIR として渡します。ツリー外のビルドは独自のインクルードパスを設定します。 2つのビルド失敗は、原因となった行とは別の場所で報告されます。 サービスの MySQL ヘッダーを省略すると、VSQL_REQUIRE_SERVICE に何も解決しない名前が残るため、エラーは不足しているインクルードではなくマクロの位置に表示されます(clang 17):
一部のサービス定義は <cstddef> を含めずに size_t を使用するため、それらのヘッダーの1つをすべての villagesql ヘッダーより前に置くと、MySQL 自身のヘッダー内で失敗します:
このページの例のように、<cstddef> を最初に含めてください。

サービスの呼び出し

サービス参照は独自の valid() を公開し、-> はサービスに転送します。参照には . を、サービスには -> を使用します:
すべての -> 呼び出しの前に valid() を確認してください。-> は取得されたポインタを返しますが、サービスが取得されなかった場合そのポインタは NULL です。 取得に失敗したサービスはインストールを失敗させるため、実行中の関数の内部では、必要なサービスは有効です。それでも確認は重要です。手動で宣言され require() に渡されなかった ServiceRef には何も書き込まれないためです。コンパイルは通り、拡張機能はインストールされ、valid() は拡張機能の生存期間を通じて false のままになります。 サービスが何であるか — そのメソッド、パラメータ、戻り値 — は、ここではなく MySQL によって文書化されています。NAME という名前のサービスについては、サーバーツリーの include/mysql/components/services/NAME.h を読んでください。その BEGIN_SERVICE_DEFINITION(NAME) ブロックが、各メソッドを独自のドキュメントとともに宣言しています。bool の戻り値が false の場合は成功、true の場合は失敗を意味するという MySQL の慣習を含め、そのヘッダーが指定するとおりに呼び出してください。

取得の失敗

宣言されたすべてのサービスは、拡張機能のロード時、その関数が呼び出せるようになる前に取得されます。そのため、登録されていないサービスは後から表面化するのではなくロードを失敗させます。INSTALL EXTENSION は失敗し、そのサービス名を示します。 以下の vsql_mysql_services_missing_test は、レジストリに存在しないサービスを必要とするツリー内のテスト拡張機能です。これはインストールできるものではありません — これは失敗を記録した方法であり、このサーバーが提供しないサービスをあなた自身の拡張機能が必要とする場合に生成される出力です:
他に2つのインストール失敗が、この機能の外側から同じ機能に到達します:MysqlServices オブジェクトを .with() に渡さない場合と、vsql_allow_preview_extensions が OFF のサーバーにインストールする場合です。どちらも登録パターンで説明しています。

完全な例

サーバーの villagesql/test-extensions/ ツリーにある vsql_mysql_services_session_test の簡略化されたバージョンです。2つのサービスを組み合わせて、呼び出し元のセッションで実行中の SQL コマンドを読み取ります。一方は現在の THD を返し、もう一方はそこから名前付き属性を読み取ります。どちらもすべてのサーバーに登録されているサーバーコアのサービスであるため、事前に何かをインストールする必要はありません:
インストールして関数を呼び出します: