系统参考

使用以下标准 SQL 接口查询扩展元数据和服务器状态。

系统视图

INFORMATION_SCHEMA.EXTENSIONS

列出所有当前安装的 VillageSQL 扩展。

INSTALL EXTENSION 和 UNINSTALL EXTENSION 是 VillageSQL SQL 扩展。它们不是 MySQL 9.7 标准语法的组成部分。

已知列：

列名	类型	描述
`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`

示例：

-- 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 版本更改。有关工作流程，请参阅管理扩展。

INFORMATION_SCHEMA.COLUMNS（自定义类型）

使用自定义扩展类型的列可以通过标准的 INFORMATION_SCHEMA.COLUMNS 视图查看。自定义类型在 DATA_TYPE 和 COLUMN_TYPE 列中显示为 extension_name.type_name（例如，vsql_complex.COMPLEX）。 示例：

-- 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 之后正确解析了扩展的函数、类型和系统变量。

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` 数组。

常用查询

查找扩展依赖项

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

SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%';

列出所有扩展及其自定义类型列

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

查找使用扩展类型的表

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] 下设置；无法在不重新启动服务器的情况下更改。

SHOW VARIABLES LIKE 'veb_dir';

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

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

仅支持单个目录。有关放置和故障排除，请参阅管理扩展。

villagesql_server_version

只读全局变量。返回编译到服务器二进制文件中的 VillageSQL 版本字符串。格式为 {codebase}_{major}.{minor}.{patch}[-prerelease]，其中 codebase 指明此构建所派生的上游分叉（此处为 mysql-9.7）。这与 villagesql_schema_version 不同，后者以相同的 {codebase}_{version} 格式报告内部元数据目录上标记的版本。

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 架构尚未初始化。

SELECT @@villagesql_schema_version;
-- Example output: mysql-9.7_0.0.6

**作用域：**全局，只读。无法在运行时设置。

villagesql_vef_server_protocol

只读全局变量。返回此服务器构建支持的最高 VEF 协议版本。安装扩展时，服务器与扩展会采用双方都支持的最高协议版本。使用已废弃的不稳定协议版本构建的扩展无法安装——INSTALL EXTENSION 会以 Failed to load VEF extension 错误失败。

SELECT @@villagesql_vef_server_protocol;

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

协议 V4 增加了对变长自定义类型的支持，并允许函数声明其字符串结果的最大长度。 V4 正在选择加入的开发版 ABI 下积极开发中，在稳定之前可能会发生变化。如果您在开发扩展，请参阅类型操作和使用 C++ 创建扩展，了解各协议版本提供的功能。该值反映了编译时常量 vef_server_protocol_version，并且无法在运行时更改。

villagesql_build_info

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

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 时，安装此类扩展会失败：

ERROR 3219 (HY000): Failed to load VEF extension 'vsql_keyring_reader': extension requires preview capabilities but vsql_allow_preview_extensions is OFF

使用 SET PERSIST 开启：

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。请先卸载这些扩展。有关可用预览功能的列表以及扩展如何使用它们，请参阅预览功能。

后续步骤

管理扩展

监控和排除扩展故障

安装扩展

添加新的扩展

扩展架构

了解内部结构

可用扩展

浏览扩展目录

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

系统视图

INFORMATION_SCHEMA.EXTENSIONS

INFORMATION_SCHEMA.COLUMNS（自定义类型）

INFORMATION_SCHEMA.EXTENSION_REGISTRATION

常用查询

查找扩展依赖项

列出所有扩展及其自定义类型列

查找使用扩展类型的表

系统变量

veb_dir

villagesql_server_version

villagesql_schema_version

villagesql_vef_server_protocol

villagesql_build_info

vsql_allow_preview_extensions

后续步骤

管理扩展

安装扩展

扩展架构

可用扩展

​系统视图

​INFORMATION_SCHEMA.EXTENSIONS

​INFORMATION_SCHEMA.COLUMNS（自定义类型）

​INFORMATION_SCHEMA.EXTENSION_REGISTRATION

​常用查询

​查找扩展依赖项

​列出所有扩展及其自定义类型列

​查找使用扩展类型的表

​系统变量

​veb_dir

​villagesql_server_version

​villagesql_schema_version

​villagesql_vef_server_protocol

​villagesql_build_info

​vsql_allow_preview_extensions

​后续步骤

管理扩展

安装扩展

扩展架构

可用扩展

系统视图

INFORMATION_SCHEMA.EXTENSIONS

INFORMATION_SCHEMA.COLUMNS（自定义类型）

INFORMATION_SCHEMA.EXTENSION_REGISTRATION

常用查询

查找扩展依赖项

列出所有扩展及其自定义类型列

查找使用扩展类型的表

系统变量

veb_dir

villagesql_server_version

villagesql_schema_version

villagesql_vef_server_protocol

villagesql_build_info

vsql_allow_preview_extensions

后续步骤