拡張機能の管理

インストール済み拡張機能の表示

INFORMATION_SCHEMA ビューを使用して、インストールされた拡張機能をクエリします：

SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

出力:

+------------------+-------------------+
| EXTENSION_NAME   | EXTENSION_VERSION |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
| vsql_uuid        | 0.0.3             |
+------------------+-------------------+

使用方法:

インタラクティブセッションとスクリプトの両方で使用可能
MySQL ツールと互換性のある標準 SQL インターフェース

拡張機能関数の確認

インストール後に拡張機能関数が正常に動作することを確認します：

-- Test a function directly
SELECT complex_abs('(1.0,2.0)');

拡張機能ディレクトリ

VillageSQL が .veb ファイルを検索する場所を確認します：

SHOW VARIABLES LIKE 'veb_dir';

利用可能な拡張機能の一覧表示:

ls -la /path/to/veb_dir/*.veb

veb_dir の設定

拡張機能ディレクトリの場所を変更するには、MySQL 設定ファイルに veb_dir を設定します： my.cnf / my.ini:

[mysqld]
veb_dir=/custom/path/to/extensions/

要件:

パスは絶対パスである必要があります（相対パス不可）
ディレクトリはサーバー起動前に存在している必要があります
MySQL ユーザーはディレクトリに対して読み取り権限を持っている必要があります
設定できる veb_dir は 1 つのみです（複数のパスは設定不可）
変更を有効にするにはサーバーの再起動が必要です

再起動後の確認:

SHOW VARIABLES LIKE 'veb_dir';

トラブルシューティング

クイックリファレンス

問題	クイック解決策
拡張機能が見つからない	`veb_dir` に正しい名前の `.veb` ファイルが存在するか確認
アクセス拒否	権限を確認: `chmod 644 extension.veb`
アンインストールできない：型が使用中	`UNINSTALL EXTENSION` を実行; エラーメッセージでブロックしている列名が特定されます
バージョンの不一致	キャッシュをクリアするためにサーバーを再起動
アップデート後に拡張機能が古い動作を表示	`UNINSTALL` 後に `INSTALL`; 必要に応じて `.veb_expansion_cache/` をクリア
型 X と Y を比較できない	両方の側で同じカスタム型を使用する必要があります
非カスタム型を暗黙的にキャストできない	比較対象のリテラルまたは列が、カスタム型と互換性がありません

拡張機能が見つからない

Error: Extension 'my_extension' not found デバッグ手順:

# 1. Check veb_dir location
mysql -u root -p -e "SHOW VARIABLES LIKE 'veb_dir';"

# 2. List .veb files
ls -la /path/to/veb_dir/

# 3. Verify filename matches extension name
# File: my_extension.veb
# Install: INSTALL EXTENSION my_extension;

# 4. Check permissions
ls -l /path/to/veb_dir/my_extension.veb
sudo chmod 644 /path/to/veb_dir/my_extension.veb

インストール後に関数が利用できない

Error: FUNCTION my_func does not exist デバッグ手順:

-- 1. Verify extension installed
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'my_extension';

アップデート後に拡張機能が古い動作を表示

症状: .veb ファイルを置き換えて再インストールした後、拡張機能がまだ古いコードを実行しています。 原因: VillageSQL は初回読み込み時に .veb ファイルを {datadir}/.veb_expansion_cache/ に展開します。UNINSTALL EXTENSION を実行せずに新しい .veb をコピーした場合、サーバーはメモリに既に読み込まれている以前に展開された .so の使用を続けます。 解決策: 常に完全な UNINSTALL → 置き換え → INSTALL のサイクルに従ってください：

UNINSTALL EXTENSION my_extension;

次に veb_dir 内の .veb ファイルを置き換えて再インストールします：

INSTALL EXTENSION my_extension;

拡張機能がまだ古い動作を表示する場合は、再インストールする前に展開キャッシュをクリアします：

rm -rf {datadir}/.veb_expansion_cache/my_extension/

INSTALL EXTENSION my_extension;

拡張機能をアンインストールできない

Error: Cannot uninstall extension: types in use 解決策:

-- Attempt uninstall; the error identifies blocking columns by name
UNINSTALL EXTENSION my_extension;
-- If blocked: ERROR HY000: Cannot drop extension `my_extension` as 1 column(s) depend on it,
--             e.g. mydb.mytable.my_column has type MYTYPE

-- Drop or alter the identified column(s), then retry
DROP TABLE mydb.mytable;
-- OR
ALTER TABLE mydb.mytable DROP COLUMN my_column;

UNINSTALL EXTENSION my_extension;

ライブラリの読み込みエラー

Error: Cannot load library: undefined symbol 原因:

必要なライブラリ依存関係の欠如
ABI 互換性の不一致
間違った MySQL バージョン

デバッグ:

# Check library dependencies (Linux)
ldd {datadir}/.veb_expansion_cache/my_extension/<sha256>/lib/my_extension.so

# Check library dependencies (macOS)
otool -L {datadir}/.veb_expansion_cache/my_extension/<sha256>/lib/my_extension.so

拡張機能名の検証エラー

Error: Failed to load VEF extension 'extension_name' with log message Extension name mismatch 原因: manifest.json 内の拡張機能名が VEB ファイル名と一致していません。 デバッグ手順:

VEB ファイル名がマニフェストと一致するか確認:

# VEB filename: my_extension.veb
# manifest.json should have:
{
  "name": "my_extension",  # Must match VEB filename (without .veb)
  ...
}

manifest.json の name フィールドを確認:

# Extract and check manifest from VEB
tar -xOf /path/to/veb_dir/my_extension.veb manifest.json | grep name

解決策: 両方の名前は一致している必要があり、アンダースコアを使用します（拡張機能の命名規則を参照）:

VEB ファイル名: my_extension.veb
manifest.json: "name": "my_extension"

一般的なミス:

マニフェストでハイフンを使用: "name": "my-extension" ❌
VEB ファイル名が一致しない: my-extension.veb vs "name": "my_extension" ❌

正しい例:

// manifest.json
{
  "name": "my_extension",
  "version": "1.0.0"
}

// extension.cc
VEF_GENERATE_ENTRY_POINTS(
  make_extension()
    .func(...)
)

# VEB filename
my_extension.veb

カスタム型の比較エラー

Error: Cannot compare types X and Y in = 原因: 比較の両側がカスタム型ですが、異なる型または拡張機能に属しています。

-- Example: comparing COMPLEX with UUID in a WHERE clause
SELECT * FROM t WHERE complex_col = uuid_col;
-- ERROR: Cannot compare types vsql_complex.COMPLEX and vsql_uuid.UUID in =

解決策: 比較の両側で同じカスタム型を使用していることを確認してください。型間で比較する必要がある場合は、適切な型変換関数を使用して明示的に変換してください。

Error: Unable to implicitly cast a non-custom type during compare with a custom type in = 原因: 比較の片側がカスタム型の列で、もう片側がその型に自動的に変換できない値（リテラルまたは列）です。

-- Example: comparing a custom type with an integer literal
SELECT * FROM t WHERE complex_col = 42;
-- ERROR: Unable to implicitly cast a non-custom type during compare...

解決策: 文字列リテラルは、型の encode 関数を使用して自動的にカスタム型にキャストされます。他の型（整数、浮動小数点数）には、明示的な変換関数を使用してください：

-- Use a string literal instead (auto-cast works)
SELECT * FROM t WHERE complex_col = '(1.0,2.0)';

-- Or use the type's from_string method explicitly
SELECT * FROM t WHERE complex_col = COMPLEX::from_string('(1.0,2.0)');

拡張機能の使用状況の監視

クエリパフォーマンス

performance_schema を使用して VDF の実行時間を追跡します：

-- Enable statement instrumentation
UPDATE performance_schema.setup_instruments
SET ENABLED = 'YES', TIMED = 'YES'
WHERE NAME LIKE '%statement%';

-- Query VDF execution times
SELECT
    DIGEST_TEXT,
    COUNT_STAR as executions,
    ROUND(SUM_TIMER_WAIT/1000000000, 2) as total_ms,
    ROUND(AVG_TIMER_WAIT/1000000000, 2) as avg_ms
FROM performance_schema.events_statements_summary_by_digest
WHERE DIGEST_TEXT LIKE '%complex_%'
ORDER BY total_ms DESC
LIMIT 10;

カスタム型の使用状況

カスタム型を使用しているテーブルを追跡します：

-- Find all columns using custom extension types
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE '%.%'
ORDER BY DATA_TYPE, TABLE_SCHEMA, TABLE_NAME;

エクステンションの更新

エクステンションを新しいバージョンに更新するには、手動更新プロセスを使用します：

ALTER EXTENSION UPDATE はまだサポートされておらず、将来のリリースで予定されています。

手動更新プロセス

現在のバージョンをアンインストールします：
UNINSTALL EXTENSION extension_name;

.veb ファイルを置き換えます：

# Remove old .veb file
sudo rm /path/to/veb_dir/extension_name.veb

# Copy new .veb file
sudo cp new_extension_name.veb /path/to/veb_dir/

新しいバージョンをインストールします：
INSTALL EXTENSION extension_name;

更新を確認します：

SELECT EXTENSION_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'extension_name';

データの安全性： テーブルがエクステンションのカスタム型を使用している場合、アンインストールする前にそれらのテーブルをドロップまたは変更する必要があります。まずデータをバックアップしてください。

例：

-- Find columns using vsql_complex types before updating
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%';

-- If columns exist, back up data and drop/alter them first
-- Then proceed with update
UNINSTALL EXTENSION vsql_complex;
-- (replace .veb file)
INSTALL EXTENSION vsql_complex;

クリーンアップ

孤立した展開ディレクトリの削除

VillageSQL は .veb ファイルを {datadir}/.veb_expansion_cache/{name}/{sha256}/ に展開します。古いバージョンは時間とともに蓄積されます。

# List expansion directories (replace {datadir} with your actual datadir path)
ls -la {datadir}/.veb_expansion_cache/

# Compare with installed extensions
mysql -u root -p -e "SELECT EXTENSION_NAME FROM INFORMATION_SCHEMA.EXTENSIONS;"

# Find the actual SHA256 directory name for a specific extension
ls {datadir}/.veb_expansion_cache/my_extension/

# Remove the unused SHA256 directory using the name shown above
rm -rf {datadir}/.veb_expansion_cache/my_extension/<sha256-from-ls>/

サーバーの再起動により、孤立した展開ディレクトリは自動的にクリーンアップされます。

レプリケーション

カスタム型には ROW 形式のバイナリログが必要です。STATEMENT および MIXED モードはサポートされていません。カスタム型のカラムを持つテーブルでは、INSERT、UPDATE、DELETE、および ALTER TABLE 操作は、ROW 形式で正しくレプリケートされます。 INSTALL EXTENSION はレプリケートされません。各サーバーは独自のエクステンションを管理します。レプリケーションを開始する前に、ソースと同じバージョンのエクステンションをすべてのレプリカにインストールしてください。サーバーは正確なバージョンの一致を強制します。バージョンが不一致だとレプリケーションが停止します。レプリカが認識しないカスタム型に遭遇した場合、レプリケーションは DDL ステートメントで停止します。 CREATE TABLE または ALTER TABLE の実行時、関連する DML が適用される前に停止します。正しいエクステンションバージョンをインストールし、再開してください：

INSTALL EXTENSION my_extension;
START REPLICA SQL_THREAD;

mysqldump は、出力に完全に修飾されたカスタム型名を保持します。論理リストアは、ダンプをインポートする前にターゲットサーバーにエクステンションがインストールされていれば機能します。

Clone プラグイン、XtraBackup、InnoDB Cluster / Group Replication での動作はまだテストされていません。本番環境で依存する前に、リストアパスをテストしてください。

Docker でのエクステンションの使用

Docker で VillageSQL を実行する際、veb_dir としてローカルディレクトリをマウントすると、コンテナを再構築せずにホストから .veb ファイルを追加できます。 Docker Compose の例：

services:
  villagesql:
    image: villagesql/server:stable
    environment:
      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
    ports:
      - "3306:3306"
    volumes:
      - ./extensions:/usr/lib/veb
    command: --veb_dir=/usr/lib/veb

ホストの ./extensions/ に .veb ファイルをコピーし、SQL からインストールします：

INSTALL EXTENSION my_extension;

実行中のサーバーが使用しているディレクトリを確認するには：

SHOW VARIABLES LIKE 'veb_dir';

サポート

ここでカバーされていない問題が発生した場合は：

エラーログを確認： ほとんどのエクステンションエラーは詳細とともにログに記録されます
エクステンションドキュメントを確認： エクステンション固有のトラブルシューティングが存在する場合があります
Discord で質問： VillageSQL Discord に参加してください
問題を報告： GitHub Issues でバグを報告してください

次のステップ

システムリファレンス

システムテーブルとビューへのクエリ

拡張機能のアンインストール

エクステンションを安全に削除

拡張機能のアーキテクチャ

内部構造の理解

Getting Started

Extensions

Using Extensions

Creating Extensions

インストール済み拡張機能の表示

拡張機能関数の確認

拡張機能ディレクトリ

veb_dir の設定

トラブルシューティング

クイックリファレンス

拡張機能が見つからない

インストール後に関数が利用できない

アップデート後に拡張機能が古い動作を表示

拡張機能をアンインストールできない

ライブラリの読み込みエラー

拡張機能名の検証エラー

カスタム型の比較エラー

拡張機能の使用状況の監視

クエリパフォーマンス

カスタム型の使用状況

エクステンションの更新

手動更新プロセス

クリーンアップ

孤立した展開ディレクトリの削除

レプリケーション

Docker でのエクステンションの使用

サポート

次のステップ

システムリファレンス

拡張機能のアンインストール

拡張機能のアーキテクチャ

​インストール済み拡張機能の表示

​拡張機能関数の確認

​拡張機能ディレクトリ

​veb_dir の設定

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

​クイックリファレンス

​拡張機能が見つからない

​インストール後に関数が利用できない

​アップデート後に拡張機能が古い動作を表示

​拡張機能をアンインストールできない

​ライブラリの読み込みエラー

​拡張機能名の検証エラー

​カスタム型の比較エラー

​拡張機能の使用状況の監視

​クエリパフォーマンス

​カスタム型の使用状況

​エクステンションの更新

​手動更新プロセス

​クリーンアップ

​孤立した展開ディレクトリの削除

​レプリケーション

​Docker でのエクステンションの使用

​サポート

​次のステップ

システムリファレンス

拡張機能のアンインストール

拡張機能のアーキテクチャ

インストール済み拡張機能の表示

拡張機能関数の確認

拡張機能ディレクトリ

veb_dir の設定

トラブルシューティング

クイックリファレンス

拡張機能が見つからない

インストール後に関数が利用できない

アップデート後に拡張機能が古い動作を表示

拡張機能をアンインストールできない

ライブラリの読み込みエラー

拡張機能名の検証エラー

カスタム型の比較エラー

拡張機能の使用状況の監視

クエリパフォーマンス

カスタム型の使用状況

エクステンションの更新

手動更新プロセス

クリーンアップ

孤立した展開ディレクトリの削除

レプリケーション

Docker でのエクステンションの使用

サポート

次のステップ