Skip to main content
VillageSQL 拡張フレームワーク（VEF）は、MySQL サーバーコードの所定の場所で拡張機能のコードを呼び出します。拡張機能の出力に対して発生するすべての処理（クラッシュリカバリ、レプリケーション、スキーマ操作、バックアップ）は、組み込みの列型を処理するのと同じ方法でサーバーによって処理されます。このドキュメントでは、その境界について説明します。VEF が何を行い、拡張機能が何を行い、その結果として得られるシステムが運用時にどのように動作するかを解説します。 このページ全体の例では、vsql-uuid 拡張機能を使用して、データの流れを説明します。

​
ABI の境界

VillageSQL 拡張機能は、バイナリインターフェース（ABI）を通じてサーバーと相互作用し、拡張機能とサーバーの間で所有権が明確に分離されています。 サーバーが所有するもの:
  • ストレージ: InnoDB はバイトの読み書きを行いますが、その内容は解釈しません。
  • スキーマ: 列型のメタデータと、どの拡張機能が各型を登録したかという情報は、VillageSQL システムテーブルに保存され、再起動後も保持されます。
  • リカバリ、レプリケーション、バックアップ: これらは、組み込みの列型と同様に、生のバイトを操作します。
  • 拡張機能の登録: 名前、バージョン、および関数/型の登録は、起動時に VillageSQL システムテーブルから再ロードされます。
拡張機能が所有するもの:
  • バイナリ形式: from_string エンコード関数が、ディスクに書き込まれる内容を定義します。to_string は、出力時にそれを読み戻します。
  • ビジネスルール: 検証、比較、ハッシュ化、エラー処理。
  • 状態: 拡張機能は、サーバーが保存するバイト以外には何も永続化しません。
完全なバイナリインターフェース（構造体、関数ポインタの typedef、プロトコルのバージョン管理）については、サーバーリポジトリの villagesql/sdk/include/villagesql/abi/types.h を参照してください。

​
カスタム型の保存方法

列を UUID（vsql-uuid の例）として宣言すると、サーバーは行ごとに固定長の生バイトブロックを保存します。人間が読める形式（d7d665f3-bb13-4c2f-b10f-d2126eb40cba など）は、境界にのみ存在します。from_string は書き込み時にそれをバイナリにエンコードし、to_string は読み取り時にそれをデコードして戻します。その間のすべて（ストレージ、redo ログ、クラッシュリカバリ、バイナリログ）は、内容を解釈せずにそれらのバイトを操作します。

​
クラッシュリカバリ

拡張機能は、サーバーの再起動時に自動的に再ロードされます。手動による介入は不要です。これは INFORMATION_SCHEMA.EXTENSION_REGISTRATION で確認できます。再起動後も、再起動前と同じ登録エントリが表示されます。 行データは、InnoDB の通常のクラッシュリカバリを通じて保持されます。拡張機能のバイナリ形式が特別扱いされることはありません。InnoDB は、UUID 列を VARBINARY 列と何ら変わりなく処理します。

​
バイナリログ形式

行形式のレプリケーション（デフォルト）では、カスタム型の値は、バイナリログ内を生のバイナリとして流れます。再エンコードのステップはありません。binlog の書き込み時に拡張機能の from_string は呼び出されず、to_string はクライアントが値を読み戻すときにのみ呼び出されます。 UUID 列の行レベルのバイナリログエントリは、次のようになります。
これら 16 個の生バイトは、変更されずにバイナリログを流れます。拡張機能がインストールされているコンシューマは、to_string を介してそれらを読み取り可能な値にデコードできます。拡張機能がないコンシューマ（外部の CDC パイプラインや binlog リーダー）には、生のバイトのみが表示されます。

​
リストア

VillageSQL サーバーのリストアは、クラッシュリカバリと同じように機能します。サーバーが起動し、拡張機能の登録を読み取り、各拡張機能を自動的にロードします。拡張機能型の列に特別な処理は必要ありません。生のバイトはバックアップ内にあり、拡張機能はオンデマンドでそれらをデコードします。 拡張機能はデータベース内には保存されず、ディスク上の veb_dir に .veb ファイルとして存在します。リストアしたインスタンスでサーバーが起動するときに VEB ファイルが見つからない場合、起動は VEB file not found で中止されます。.veb_expansion_cache は、.veb 自体の代わりにはなりません。拡張機能を配布するときは、バックアップやサーバー移行の際に、データディレクトリと一緒に veb_dir を含める必要があることをユーザーに周知してください。

​
スキーマ操作

拡張機能型の列を持つテーブルに対する ALTER TABLE は、組み込み型の場合とまったく同じように動作します。サーバーは、列の拡張機能バインディングをスキーマメタデータで追跡し、そのバインディングはテーブルの再構築後も保持されます。vsql-uuid の id 列を持つテーブルに他の列を追加または変更しても、UUID データはそのまま残ります。