拡張機能の管理

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

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 を使用します。これは既存のデータに対して新しいバージョンを検証し、次回サーバーが再起動したときに変更を適用します。代替手段として、手動でのアンインストールと再インストールも引き続き利用できます。

拡張機能のバージョン変更

ALTER EXTENSION はインストール済みの拡張機能を別のバージョンに変更し、次回のサーバー再起動時に適用します：

ALTER EXTENSION update_test VERSION '1.2.0' AT RESTART;

VillageSQL は対象バージョンをディスク上で解決し、変更を受け入れる前に互換性の事前チェックを実行します。対象の VEB は拡張機能ディレクトリに <name>-<version>.veb（ここでは update_test-1.2.0.veb）として存在している必要があります。ファイルが存在しない場合は拒否されます：

ERROR 3219 (HY000): VEB file not found: update_test-9.9.9.veb

事前チェックは、保存済みデータを破損させる既知の非互換性を探します。たとえば、カスタム型の永続化長の変更などです：

ERROR 3219 (HY000): Cannot update extension 'update_test': type 'COUNTER'
persisted_length changed from 4 to 8 -- existing stored data would be corrupted

受け入れられると、変更は次回の再起動時に適用されます。それまでの間、 INFORMATION_SCHEMA.EXTENSIONS は現在のバージョンと、変更予定の対象バージョンを並べて報告します：

SELECT EXTENSION_NAME, EXTENSION_VERSION, PENDING_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'update_test';

+----------------+-------------------+-----------------+
| EXTENSION_NAME | EXTENSION_VERSION | PENDING_VERSION |
+----------------+-------------------+-----------------+
| update_test    | 1.0.0             | 1.2.0           |
+----------------+-------------------+-----------------+

INFORMATION_SCHEMA.EXTENSIONS は予定された変更を 4 つの列で報告します：

列	意味
`PENDING_VERSION`	次回の再起動時に拡張機能が変更されるバージョン、または `NULL`
`PENDING_REQUESTED_AT`	変更が要求された日時
`PENDING_LAST_ERROR`	失敗した変更のメッセージ、または `NULL`
`PENDING_LAST_ERROR_AT`	その失敗が記録された日時、または `NULL`

予定された変更は一度に 1 つだけ追跡されます：

予定された変更をキャンセルするには、現在のバージョンを再度要求します：

ALTER EXTENSION update_test VERSION '1.0.0' AT RESTART;
-- Note: Cleared pending update for extension 'update_test'
--       (target matches current version '1.0.0')

何も予定されていないときに現在のバージョンを要求しても何も起こりません：

ALTER EXTENSION update_test VERSION '1.0.0' AT RESTART;
-- Note: Extension 'update_test' is already at version '1.0.0'

変更が予定されている間は別の対象は拒否されます — まず既存のものをキャンセルしてください：

ERROR 3219 (HY000): Extension 'update_test' already has a pending update;
clear it with ALTER EXTENSION update_test VERSION '1.0.0' AT RESTART before
queueing a different version

AT RESTART 句は、次回のサーバー起動時に変更を適用します。

再起動が成功した後

次回の再起動時に、保留中の変更が適用されます。EXTENSION_VERSION が対象バージョンになり、 PENDING_VERSION がクリアされます。上記で予定した変更（update_test 1.0.0 → 保留中 1.2.0）の場合：

SELECT EXTENSION_NAME, EXTENSION_VERSION, PENDING_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'update_test';

+----------------+-------------------+-----------------+
| EXTENSION_NAME | EXTENSION_VERSION | PENDING_VERSION |
+----------------+-------------------+-----------------+
| update_test    | 1.2.0             | NULL            |
+----------------+-------------------+-----------------+

古いバージョンを参照する custom_columns およびストアドプロシージャのパラメータの行は、同じ再起動中にすべて書き換えられるため、依存するテーブルとルーチンは手動での移行なしに動作を継続します。

変更はライブ接続上ではなく再起動中に適用されます — 上記の値は再起動後の状態です。

起動時の保留中バージョン変更からの回復

予定されたバージョン変更は、次回のサーバー起動時に適用されます。保留中のアクションを適用できない場合、サーバーは保留中の更新に関する判断内容をディスクに記録したまま、起動に失敗することがあります。キューに入れられた ALTER EXTENSION ... AT RESTART が起動をブロックしていて、それをクリアする前にサーバーを起動する必要がある場合は、 --villagesql-skip-extension-updates を使用してください。 --villagesql-skip-extension-updates は mysqld の起動フラグです。設定すると、サーバーは保留中の ALTER EXTENSION ... AT RESTART アクションの処理をバイパスします。各拡張機能は現在インストールされているバージョンで読み込まれ、その保留中のアクションはディスク上にそのまま残されます。このフラグ自体は何も変更しません — その 1 回の起動に対して保留中のアクションの適用をスキップするだけです。フラグが設定され、少なくとも 1 つの拡張機能に保留中のアクションがある場合、サーバーは起動時に、バイパスされた数を示す単一の警告をログに記録します：

--villagesql-skip-extension-updates is set: bypassing N pending extension update(s). Extensions load at their currently-installed version. Query INFORMATION_SCHEMA.EXTENSIONS to see the pending actions; clear each via ALTER EXTENSION <name> VERSION '<current>' AT RESTART, then restart without the flag.

フラグ付きでサーバーを起動する

本番環境では、通常の mysqld コマンドラインオプションとして渡すか、 my.cnf の [mysqld] の下に追加します：

mysqld --villagesql-skip-extension-updates

開発ハーネスでは、-- を使って渡します：

./villagesql start -- --villagesql-skip-extension-updates

成功のサイン: サーバーが起動し、エラーログに上記の bypassing N pending extension update(s) 警告が含まれます。

保留中のアクションを特定する

SELECT EXTENSION_NAME, EXTENSION_VERSION, PENDING_VERSION, PENDING_LAST_ERROR
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE PENDING_VERSION IS NOT NULL;

+--------------+-------------------+-----------------+--------------------+
| EXTENSION_NAME | EXTENSION_VERSION | PENDING_VERSION | PENDING_LAST_ERROR |
+--------------+-------------------+-----------------+--------------------+
| my_extension   | 1.0.0             | 2.0.0           | NULL               |
+--------------+-------------------+-----------------+--------------------+

成功のサイン: 各行の PENDING_VERSION はクリアが必要な対象です。 PENDING_LAST_ERROR は適用に失敗した理由を示します。

各保留中アクションをクリアする

上記で返された各拡張機能について、現在のバージョンを要求してキューに入れられた変更をキャンセルします（拡張機能のバージョン変更で説明したキャンセルの仕組み）：

ALTER EXTENSION my_extension VERSION '1.0.0' AT RESTART;

成功のサイン: Cleared pending update for extension '<name>' (target matches current version '<current>') というノートが返され、前のクエリを再実行すると PENDING_VERSION が NULL になっています。

フラグなしで再起動する

--villagesql-skip-extension-updates を省略して、サーバーを通常どおり再起動します。成功のサイン: サーバーが起動し、ログに bypassing N pending extension update(s) 警告が表示されなくなります。

手動更新プロセス

現在のバージョンをアンインストールします：
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

Server Development

Extensions

Using Extensions

Creating Extensions

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

拡張機能関数の確認

拡張機能ディレクトリ

veb_dir の設定

トラブルシューティング

クイックリファレンス

拡張機能が見つからない

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

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

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

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

拡張機能名の検証エラー

カスタム型の比較エラー

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

クエリパフォーマンス

カスタム型の使用状況

拡張機能の更新

拡張機能のバージョン変更

再起動が成功した後

起動時の保留中バージョン変更からの回復

手動更新プロセス

クリーンアップ

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

レプリケーション

Docker での拡張機能の使用

サポート

次のステップ

システムリファレンス

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

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

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

​拡張機能関数の確認

​拡張機能ディレクトリ

​veb_dir の設定

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

​クイックリファレンス

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

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

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

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

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

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

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

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

​クエリパフォーマンス

​カスタム型の使用状況

​拡張機能の更新

​拡張機能のバージョン変更

​再起動が成功した後

​起動時の保留中バージョン変更からの回復

​手動更新プロセス

​クリーンアップ

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

​レプリケーション

​Docker での拡張機能の使用

​サポート

​次のステップ

システムリファレンス

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

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

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

拡張機能関数の確認

拡張機能ディレクトリ

veb_dir の設定

トラブルシューティング

クイックリファレンス

拡張機能が見つからない

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

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

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

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

拡張機能名の検証エラー

カスタム型の比較エラー

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

クエリパフォーマンス

カスタム型の使用状況

拡張機能の更新

拡張機能のバージョン変更

再起動が成功した後

起動時の保留中バージョン変更からの回復

手動更新プロセス

クリーンアップ

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

レプリケーション

Docker での拡張機能の使用

サポート

次のステップ