> ## 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>

**已知列：**

| 列名                      | 类型       | 描述                          |
| ----------------------- | -------- | --------------------------- |
| `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()` 的名称匹配。

该视图反映当前的安装状态。

这四个 `PENDING_*` 列跟踪已计划的 `ALTER EXTENSION ... AT RESTART`
版本更改。有关工作流程，请参阅 [管理扩展](/docs/zh/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';
```

| 列名                    | 类型                | 描述                                                         |
| --------------------- | ----------------- | ---------------------------------------------------------- |
| `EXTENSION_NAME`      | `VARCHAR(64)`     | 已安装扩展的名称。                                                  |
| `NEGOTIATED_PROTOCOL` | `BIGINT UNSIGNED` | 扩展和服务器之间协商的 VEF 协议版本。                                      |
| `REGISTRATION_JSON`   | `VARCHAR(65535)`  | `vef_registration_t` 结构的 JSON 序列化，包括 `funcs` 和 `types` 数组。 |

***

## 常用查询

### 查找扩展依赖项

在卸载扩展之前，查找哪些列使用了特定扩展的类型：

```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` 扩展包文件的目录路径。在 `my.cnf` 的 `[mysqld]` 下设置；无法在不重新启动服务器的情况下更改。

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

\*\*作用域：\*\*全局，运行时只读。在 `my.cnf` 中配置：

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

仅支持单个目录。有关放置和故障排除，请参阅 [管理扩展](/docs/zh/mysql-9.7/stable/managing)。

***

### villagesql\_server\_version

只读全局变量。返回编译到服务器二进制文件中的 VillageSQL 版本字符串。格式为
`{codebase}_{major}.{minor}.{patch}[-prerelease]`，其中 `codebase` 指明此构建
所派生的上游分叉（此处为 `mysql-9.7`）。这与 `villagesql_schema_version` 不同，
后者以相同的 `{codebase}_{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;
```

| 属性       | 值                      |
| -------- | ---------------------- |
| **作用域**  | 全局                     |
| **访问权限** | 只读                     |
| **类型**   | 无符号整数（`0`–`255`）       |
| **当前值**  | `4` (`VEF_PROTOCOL_4`) |

协议 V4 增加了对变长自定义类型的支持，并允许函数声明其字符串结果的最大长度。
V4 正在选择加入的开发版 ABI 下积极开发中，在稳定之前可能会发生变化。如果您在
开发扩展，请参阅 [类型操作](/docs/zh/mysql-9.7/stable/type-operations) 和
[使用 C++ 创建扩展](/docs/zh/mysql-9.7/stable/create)，了解各协议版本提供的功能。

该值反映了编译时常量 `vef_server_protocol_version`，并且无法在运行时更改。

***

### villagesql\_build\_info

只读全局变量。返回一个 JSON 对象，其中包含有关此服务器二进制文件如何构建的
元数据：源提交、工作树状态和构建环境。

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

| 字段                | 类型      | 描述                                                   |
| ----------------- | ------- | ---------------------------------------------------- |
| `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`。发布构建（版本号不带预发布后缀的构建）
会将这三个计数强制归零，并将 `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 PERSIST`，而不是 `SET GLOBAL`。预览扩展在服务器启动时加载，因此该值必须在重启后仍然有效，而只有 `SET PERSIST` 会将其写入 `mysqld-auto.cnf`；因此 `SET GLOBAL` 会被拒绝。在 `mysqld-auto.cnf` 尚不存在之前（例如服务器首次启动时），请改为在 `mysqld` 命令行中传入 `--vsql_allow_preview_extensions=ON`。

只要仍有使用预览功能的扩展处于已安装状态，就无法将该值重新关闭，因为这些扩展要求服务器启动时该设置为 ON。请先卸载这些扩展。

有关可用预览功能的列表以及扩展如何使用它们，请参阅[预览功能](/docs/zh/mysql-9.7/stable/preview-capabilities)。

***

## 后续步骤

<CardGroup cols={2}>
  <Card title="管理扩展" icon="sliders" href="/docs/zh/mysql-9.7/stable/managing">
    监控和排除扩展故障
  </Card>

  <Card title="安装扩展" icon="download" href="/docs/zh/mysql-9.7/stable/install">
    添加新的扩展
  </Card>

  <Card title="扩展架构" icon="sitemap" href="/docs/zh/mysql-9.7/stable/architecture">
    了解内部结构
  </Card>

  <Card title="可用扩展" icon="list" href="/docs/zh/mysql-9.7/stable/extensions">
    浏览扩展目录
  </Card>
</CardGroup>