> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# システムリファレンス

> 拡張メタデータとサーバーの状態を照会するためのVillageSQLシステムビューと変数

以下の標準SQLインターフェースを使用して、拡張メタデータとサーバーの状態を照会します。

***

## システムビュー

### INFORMATION\_SCHEMA.EXTENSIONS

現在インストールされているVillageSQL拡張の一覧を表示します。

<Note>
  `INSTALL EXTENSION` と `UNINSTALL EXTENSION` はVillageSQLのSQL拡張機能です。
  これらは標準的なMySQL 9.7の構文には含まれていません。
</Note>

**既知の列：**

| Column                  | Type     | Description                          |
| ----------------------- | -------- | ------------------------------------ |
| `EXTENSION_NAME`        | varchar  | インストールされた拡張機能の名前                     |
| `EXTENSION_VERSION`     | varchar  | 拡張機能から報告されたバージョン文字列                  |
| `PENDING_VERSION`       | longtext | 次回の再起動時に拡張機能が切り替わる先のバージョン、または `NULL` |
| `PENDING_REQUESTED_AT`  | longtext | 保留中のバージョン変更が要求された日時、または `NULL`       |
| `PENDING_LAST_ERROR`    | longtext | 失敗したバージョン変更からのメッセージ、または `NULL`       |
| `PENDING_LAST_ERROR_AT` | longtext | その失敗が記録された日時、または `NULL`              |

**例：**

```sql theme={null}
-- Install an extension (VillageSQL-specific syntax)
INSTALL EXTENSION vsql_complex;

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

-- Check a specific extension's version
SELECT EXTENSION_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_complex';
```

**出力例**（実際のバージョン文字列はインストールされた拡張機能に依存します）：

```
+------------------+-------------------+
| EXTENSION_NAME   | EXTENSION_VERSION |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
| vsql_uuid        | 0.2.1             |
+------------------+-------------------+
```

`EXTENSION_NAME` の値は小文字で、`make_extension()` に渡された名前と一致します。

このビューは現在のインストール状態を反映します。

4つの `PENDING_*` 列は、スケジュールされた `ALTER EXTENSION ... AT RESTART`
のバージョン変更を追跡します。ワークフローについては [拡張機能の管理](/docs/ja/mysql-9.7/stable/managing) を参照してください。

***

### INFORMATION\_SCHEMA.COLUMNS (カスタム型)

カスタム拡張型を使用する列は、標準的な
`INFORMATION_SCHEMA.COLUMNS` ビューで確認できます。カスタム型は
`DATA_TYPE` および `COLUMN_TYPE` 列に
`extension_name.type_name` 形式で表示されます
（例：`vsql_complex.COMPLEX`）。

**例：**

```sql theme={null}
-- 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 TABLE_SCHEMA, TABLE_NAME;

-- Find columns using a specific extension's types
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%';
```

**出力例：**

```
+--------------+------------+-------------+---------------------+
| TABLE_SCHEMA | TABLE_NAME | COLUMN_NAME | DATA_TYPE           |
+--------------+------------+-------------+---------------------+
| mydb         | signals    | impedance   | vsql_complex.COMPLEX|
| mydb         | signals    | frequency   | vsql_complex.COMPLEX|
+--------------+------------+-------------+---------------------+
```

***

### INFORMATION\_SCHEMA.EXTENSION\_REGISTRATION

読み込まれた各拡張機能のメモリ内VEF登録構造体をJSONドキュメントとして公開します。`INSTALL EXTENSION` 実行後に、サーバーが拡張機能の関数、型、システム変数を正しくパースしたことを確認するために使用します。

```sql theme={null}
SELECT EXTENSION_NAME, NEGOTIATED_PROTOCOL, REGISTRATION_JSON
FROM INFORMATION_SCHEMA.EXTENSION_REGISTRATION
WHERE EXTENSION_NAME = 'vsql_complex';
```

| Column                | Type              | Description                                                    |
| --------------------- | ----------------- | -------------------------------------------------------------- |
| `EXTENSION_NAME`      | `VARCHAR(64)`     | インストールされた拡張機能の名前。                                              |
| `NEGOTIATED_PROTOCOL` | `BIGINT UNSIGNED` | 拡張機能とサーバー間でネゴシエートされたVEFプロトコルバージョン。                             |
| `REGISTRATION_JSON`   | `VARCHAR(65535)`  | `funcs` および `types` 配列を含む `vef_registration_t` 構造体のJSONシリアライズ。 |

***

## 一般的なクエリ

### 拡張機能の依存関係の検索

アンインストールする前に、特定の拡張機能の型を使用している列を特定します：

```sql theme={null}
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%';
```

### すべての拡張機能とそのカスタム型列の一覧表示

```sql theme={null}
-- All installed extensions
SELECT EXTENSION_NAME, EXTENSION_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
ORDER BY EXTENSION_NAME;

-- All columns using custom types across all extensions
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;
```

### 拡張機能の型を使用しているテーブルの検索

```sql theme={null}
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%'
ORDER BY TABLE_SCHEMA, TABLE_NAME;
```

***

## システム変数

### veb\_dir

実行時に読み取り専用です。サーバーが `.veb` 拡張バンドルファイルを検索するディレクトリのパスを示します。`[mysqld]` セクションの `my.cnf` で設定します。サーバーの再起動なしでは変更できません。

```sql theme={null}
SHOW VARIABLES LIKE 'veb_dir';
```

**スコープ：** グローバル、実行時に読み取り専用。`my.cnf` で設定：

```ini theme={null}
[mysqld]
veb_dir=/path/to/extensions/
```

サポートされるのは単一のディレクトリのみです。配置とトラブルシューティングについては、[拡張機能の管理](/docs/ja/mysql-9.7/stable/managing) を参照してください。

***

### villagesql\_server\_version

読み取り専用のグローバル変数です。サーバーバイナリにコンパイルされたVillageSQLバージョン文字列を返します。フォーマットは
`{codebase}_{major}.{minor}.{patch}[-prerelease]` であり、`codebase` はこのビルドの派生元となる上流フォークを指します（ここでは `mysql-9.7`）。これは内部メタデータカタログにスタンプされたバージョンを同じ `{codebase}_{version}` 形式で報告する `villagesql_schema_version` とは別物です。

```sql theme={null}
SELECT @@villagesql_server_version;
-- Example output: mysql-9.7_0.0.6

-- All VillageSQL system variables at once. Not every one of them starts with
-- villagesql_, so a LIKE 'villagesql_%' pattern on its own misses some.
SHOW VARIABLES WHERE Variable_name LIKE 'villagesql\_%'
  OR Variable_name IN ('veb_dir', 'vsql_allow_preview_extensions');
```

**スコープ：** グローバル、読み取り専用。実行時に設定できません。

***

### villagesql\_schema\_version

読み取り専用のグローバル変数です。内部メタデータカタログにスタンプされたバージョンを、`villagesql_server_version` と同じ `{codebase}_{version}` 形式で返します。空文字列は、このデータディレクトリで VillageSQL スキーマが初期化されていないことを意味します。

```sql theme={null}
SELECT @@villagesql_schema_version;
-- Example output: mysql-9.7_0.0.6
```

**スコープ：** グローバル、読み取り専用。実行時に設定できません。

***

### villagesql\_vef\_server\_protocol

読み取り専用のグローバル変数です。このサーバービルドでサポートされている最高のVEFプロトコルバージョンを返します。拡張機能のインストール時には、サーバーと拡張機能の双方がサポートする最高のプロトコルバージョンが使用されます。廃止された不安定プロトコルバージョンでビルドされた拡張機能はインストールできず、`INSTALL EXTENSION` は `Failed to load VEF extension` エラーで失敗します。

```sql theme={null}
SELECT @@villagesql_vef_server_protocol;
```

| Property | Value                  |
| -------- | ---------------------- |
| **スコープ** | グローバル                  |
| **アクセス** | 読み取り専用                 |
| **型**    | 符号なし整数 (`0`–`255`)     |
| **現在の値** | `4` (`VEF_PROTOCOL_4`) |

プロトコル V4 は、可変長カスタム型のサポートを追加し、関数が文字列結果の最大長を
宣言できるようにします。V4 はオプトインの開発版 ABI の下で活発に開発が進められており、
安定化する前に変更される可能性があります。拡張機能を開発する場合は、各プロトコル
バージョンで利用可能になる機能について
[タイプ操作](/docs/ja/mysql-9.7/stable/type-operations) と
[C++での拡張機能の作成](/docs/ja/mysql-9.7/stable/create) を参照してください。

この値はコンパイル時の定数 `vef_server_protocol_version`
を反映しており、実行時に変更することはできません。

***

### villagesql\_build\_info

読み取り専用のグローバル変数です。このサーバーバイナリがどのようにビルドされたかに関するメタデータ（ソースコミット、ワークツリーの状態、およびビルド環境）を含む JSON オブジェクトを返します。

```sql theme={null}
SELECT @@villagesql_build_info;
```

| Field             | Type    | Description                                                     |
| ----------------- | ------- | --------------------------------------------------------------- |
| `git_sha`         | string  | 40文字のソースコミットSHA全体、利用できない場合は `"unknown"`                         |
| `is_dirty`        | bool    | ビルド時にワークツリーに未コミットの変更があった場合は `true`                              |
| `files_added`     | integer | ビルド時に追加または未追跡だったファイル                                            |
| `files_deleted`   | integer | ビルド時に削除されたファイル                                                  |
| `files_modified`  | integer | ビルド時に変更されたファイル                                                  |
| `build_timestamp` | string  | ISO-8601 UTC タイムスタンプ、例：`"2026-06-17T12:34:56Z"`。リリースビルドでは空になります |
| `build_host`      | string  | ビルドマシンのホスト名。リリースビルドでは空になります                                     |
| `build_os`        | string  | ホストのオペレーティングシステム：`"Linux-6.18.15"` または `"Darwin-24.3.0"`        |
| `build_arch`      | string  | ホストのCPUアーキテクチャ：`"x86_64"`、`"aarch64"`、または `"arm64"`             |

**スコープ：** グローバル、読み取り専用。実行時に設定できません。

変更されたワークツリーからのビルドでは、`files_added`、`files_deleted`、または
`files_modified` にゼロ以外の数が表示され、その場合 `is_dirty` は `true` になります。
リリースビルド（バージョンにプレリリースのサフィックスが付いていないビルド）では、
同一のソースから同一のバイナリが生成されるように、この3つのカウントが強制的にゼロになり、
`build_timestamp` と `build_host` が空になります。これが、リリースビルドでは常に
`is_dirty` が `false` になる理由です。

***

### vsql\_allow\_preview\_extensions

プレビュー機能を必要とする拡張機能をサーバーが受け入れるかどうかを制御します。`OFF` の間は、そのような拡張機能のインストールが失敗します：

```text theme={null}
ERROR 3219 (HY000): Failed to load VEF extension 'vsql_keyring_reader': extension requires preview capabilities but vsql_allow_preview_extensions is OFF
```

`SET PERSIST` で有効にします：

```sql theme={null}
SET PERSIST vsql_allow_preview_extensions = ON;
```

| Property  | Value                    |
| --------- | ------------------------ |
| **スコープ**  | グローバル                    |
| **アクセス**  | 読み取り可能。`SET PERSIST` で設定 |
| **型**     | ブール値                     |
| **デフォルト** | `OFF`                    |

`SET GLOBAL` ではなく `SET PERSIST` を使用してください。プレビュー拡張機能はサーバー起動時にロードされるため、この値は再起動後も保持される必要があり、`mysqld-auto.cnf` に書き込むのは `SET PERSIST` だけです。そのため `SET GLOBAL` は拒否されます。`mysqld-auto.cnf` がまだ存在しない場合（サーバーを初めて起動する場合など）は、代わりに `mysqld` のコマンドラインで `--vsql_allow_preview_extensions=ON` を渡してください。

プレビュー機能を使用する拡張機能が1つでもインストールされている間は、この値をOFFに戻すことはできません。サーバー起動時にこの設定がONである必要があるためです。まず該当する拡張機能をアンインストールしてください。

利用可能なプレビュー機能の一覧と、拡張機能がそれらをどう使うかについては、[プレビュー機能](/docs/ja/mysql-9.7/stable/preview-capabilities) を参照してください。

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="拡張機能の管理" icon="sliders" href="/docs/ja/mysql-9.7/stable/managing">
    拡張機能の監視とトラブルシューティング
  </Card>

  <Card title="拡張機能のインストール" icon="download" href="/docs/ja/mysql-9.7/stable/install">
    新しい拡張機能の追加
  </Card>

  <Card title="拡張機能のアーキテクチャ" icon="sitemap" href="/docs/ja/mysql-9.7/stable/architecture">
    内部構造の理解
  </Card>

  <Card title="利用可能な拡張機能" icon="list" href="/docs/ja/mysql-9.7/stable/extensions">
    拡張機能カタログの閲覧
  </Card>
</CardGroup>