拡張機能のインストール

データベースにカスタムの型、関数、および機能を追加するには、VillageSQLの拡張機能をインストールします。

コマンド構文

INSTALL EXTENSION extension_name [VERSION 'version'];

VERSION が指定されると、サーバーは {name}-{version}.veb を開き、バージョンをマニフェストと照合し、一致しない場合は中止します。

ERROR 3219 (HY000): Version mismatch in '<file>': filename says 'X' but manifest says 'Y'

この句を省略すると {name}.veb がインストールされます。または、バージョン付きの VEB のみが存在する場合は、一意の {name}-{version}.veb がインストールされます。バージョンの選択を参照してください。

拡張機能は、コンパイルされたライブラリとメタデータを含む.veb（VillageSQL拡張機能バンドル）ファイルとして配布されます。

バージョンの選択

veb_dir 内の VEB ファイルの名前は、{name}.veb（バージョンなし）または {name}-{version}.veb（バージョン付き）のいずれかになります。特定のバージョン付き VEB をインストールするには、VERSION 句を追加します。

INSTALL EXTENSION vsql_uuid VERSION '0.2.0';

VERSION を指定すると、サーバーは vsql_uuid-0.2.0.veb を開き、その manifest.json 内のバージョンが 0.2.0 と一致することを確認します。 VERSION を指定しない場合、サーバーは次のようにファイルを解決します。

{name}.veb が存在する場合は、それをインストールします。バージョンはその manifest.json から読み取られます。
それ以外の場合、{name}-{version}.veb がちょうど 1 つ存在すれば、それをインストールします。ファイル名内のバージョンはその manifest.json と照合して検証されます。
それ以外の場合、インストールは失敗し、バージョンを指定する必要があります。

複数のバージョン付き VEB が存在し、バージョンなしの VEB が存在しない場合、INSTALL EXTENSION は

Multiple versions of extension '<name>' found in '<dir>'; specify a version with INSTALL EXTENSION <name> VERSION 'x.y.z'

で失敗します。明示的な VERSION 句を付けて再実行してください。

拡張機能の命名規則

VillageSQLは、異なるコンテキストで異なる命名規則を使用します。

SQLコマンド: アンダースコアを使用します: INSTALL EXTENSION vsql_uuid
リポジトリ名: ハイフンを使用します: github.com/villagesql/vsql-uuid
ファイル名: アンダースコアを使用します: vsql_uuid.veb
manifest.json: SQLと一致するようにアンダースコアを使用します: "name": "vsql_uuid"

例:

# Clone from GitHub repo (hyphens in URL)
git clone https://github.com/villagesql/vsql-uuid

# But .veb file uses underscores
ls vsql_uuid.veb

# Install with underscores (no quotes)
INSTALL EXTENSION vsql_uuid;

必要な権限

INSTALL EXTENSION、UNINSTALL EXTENSION、および ALTER EXTENSION は、 EXTENSION_ADMIN 動的権限によって保護されています。これらのステートメントは、実行中のサーバーにネイティブの拡張機能コードをロードするため、管理権限を必要とし、権限のないアカウントでは使用できません。 EXTENSION_ADMIN は、グローバルスコープ（ON *.*）で付与される動的権限です。

GRANT EXTENSION_ADMIN ON *.* TO user@host;

下位互換性のためのフォールバックとして SUPER も受け入れられます。そのため、すでに SUPER を保持しているアカウントは、別途付与を受けなくてもこれらのステートメントを実行できます。 --initialize または --initialize-insecure によって作成されたデータディレクトリは、 root@localhost に EXTENSION_ADMIN を直接付与するため、新しいサーバーで手動の付与は不要です。既存のデータディレクトリをその場でアップグレードした場合、SUPER を保持するすべてのユーザーアカウントに EXTENSION_ADMIN が付与されます。ただしこれは、いずれのアカウントもまだその権限を保持していない場合に限られるため、一度アップグレードされたサーバーが後のアップグレードで再度補填されることはありません。予約された mysql.* システムアカウントは除外されます。どちらの権限も持たないアカウントは、拡張機能の処理が始まる前に拒否されます。

ERROR 1227 (42000): Access denied; you need (at least one of) the EXTENSION_ADMIN or SUPER privilege(s) for this operation

権限の取り消しも同じ方法で行います。

REVOKE EXTENSION_ADMIN ON *.* FROM user@host;

取り消しは次回の接続時ではなく、直ちに有効になります。サーバーは、拡張機能の DDL ステートメントごとに、アカウントの現在の権限に対して EXTENSION_ADMIN/SUPER をチェックします。そのため、既存のセッションが取り消し後も権限を保持し続けることはありません。そのセッションの次のステートメントは、上に示したものと同じ ERROR 1227 (42000) で失敗します。

前提条件

実行中のVillageSQLサーバーインスタンス
管理者権限（rootまたは同等の権限）

組み込み拡張機能のインストール

VillageSQLに付属する組み込み拡張機能は、すでにveb_dirにあります。単に有効にするだけです。

-- Connect to VillageSQL
mysql -u root -p

-- Install the extension
INSTALL EXTENSION vsql_complex;

インストールの確認

-- List installed extensions
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

出力:

+----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+
| EXTENSION_NAME | EXTENSION_VERSION | PENDING_VERSION | PENDING_REQUESTED_AT | PENDING_LAST_ERROR | PENDING_LAST_ERROR_AT |
+----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+
| vsql_complex   | 0.0.1             | NULL            | NULL                 | NULL               | NULL                  |
+----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+

機能のテスト

-- Create a database first
CREATE DATABASE test_db;
USE test_db;

-- Test extension functions
CREATE TABLE test (id INT, value COMPLEX);
INSERT INTO test VALUES (1, '(3,4)');
SELECT complex_abs(value) FROM test;  -- Returns 5.0

-- Clean up
DROP TABLE test;
DROP DATABASE test_db;

外部拡張機能のインストール

別途ダウンロードまたは構築された拡張機能の場合:

外部拡張機能をインストールする前に、サーバーでveb_dirを構成する必要があります。 veb_dirの構成を参照してください。

1. .vebファイルのコピー

サーバーの拡張機能ディレクトリを見つけて、そこに.vebファイルをコピーします。

-- Find the extension directory
SHOW VARIABLES LIKE 'veb_dir';

cp /path/to/my_extension.veb /path/to/veb_dir/

2. 拡張機能のインストール

INSTALL EXTENSION my_extension;

想定されるバージョンを固定するには（CI やスクリプト化されたロールアウトで役立ちます）、 VERSION 句を含めます。

INSTALL EXTENSION my_extension VERSION '1.2.0';

マニフェストが異なるバージョンを報告する場合、インストールは失敗し、何も登録されません。

ERROR 3219 (HY000): Cannot install extension 'my_extension': manifest version
is '0.0.1' but VERSION '1.2.0' was specified

これはフォールバックファイルのパス（{name}-{version}.veb が存在しない場合）です。先に示した Version mismatch in '<file>' エラーとは異なるコードパスであり、そちらはバージョン付きのファイル自体が存在する場合に発生します。

3. インストールの確認

SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'my_extension';

トラブルシューティング

問題	解決策
`Extension not found`	`.veb`ファイルが`veb_dir`にあることを確認します: `SHOW VARIABLES LIKE 'veb_dir'`
`Permission denied`	ファイルのアクセス許可を確認します: `chmod 644 extension.veb`
`extension name mismatch`	拡張機能の内部名が`.veb`ファイル名と一致しません。拡張機能を再構築します。
`vef_register not found: ...`	`.veb`ファイルが有効なVEFエントリポイントをエクスポートしていません。正しいSDKに対して再構築します。
`vef_register returned an error: ...`	拡張機能の登録に失敗しました。付加されたメッセージを読んで詳細を確認してください。
`Cannot install extension 'name': manifest version is 'X' but VERSION 'Y' was specified`	`VERSION` 句が `{name}-{version}.veb` を選択しますが、内部のマニフェストが異なるバージョンを報告しています。マニフェストのバージョンで再実行するか、ファイル名を修正してください。
`Multiple versions of extension 'name' found in '<dir>'; specify a version with INSTALL EXTENSION name VERSION 'x.y.z'`	バージョンなしの `{name}.veb` がなく、複数の `{name}-{version}.veb` ファイルが存在します。明示的な `VERSION` 句を付けて再実行してください。

さらにトラブルシューティングについては、拡張機能の管理を参照してください。

次のステップ

拡張機能の管理

インストールされた拡張機能を監視およびトラブルシューティングします。

利用可能な拡張機能

インストールできる拡張機能を参照します。

拡張機能の作成

独自の拡張機能を構築します。

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

コマンド構文

バージョンの選択

拡張機能の命名規則

必要な権限

前提条件

組み込み拡張機能のインストール

インストールの確認

機能のテスト

外部拡張機能のインストール

1. .vebファイルのコピー

2. 拡張機能のインストール

3. インストールの確認

トラブルシューティング

次のステップ

拡張機能の管理

利用可能な拡張機能

拡張機能の作成

​コマンド構文

​バージョンの選択

​拡張機能の命名規則

​必要な権限

​前提条件

​組み込み拡張機能のインストール

​インストールの確認

​機能のテスト

​外部拡張機能のインストール

​1. .vebファイルのコピー

​2. 拡張機能のインストール

​3. インストールの確認

​トラブルシューティング

​次のステップ

拡張機能の管理

利用可能な拡張機能

拡張機能の作成

コマンド構文

バージョンの選択

拡張機能の命名規則

必要な権限

前提条件

組み込み拡張機能のインストール

インストールの確認

機能のテスト

外部拡張機能のインストール

1. .vebファイルのコピー

2. 拡張機能のインストール

3. インストールの確認

トラブルシューティング

次のステップ