安装扩展

安装 VillageSQL 扩展，以向数据库添加自定义类型、函数和功能。

命令语法

INSTALL EXTENSION extension_name [VERSION 'version'];

提供 VERSION 时，服务器会打开 {name}-{version}.veb，将该版本与清单进行比较，如果两者不一致则中止安装：

ERROR 3219 (HY000): Version mismatch in '<file>': filename says 'X' but manifest says 'Y'

省略该子句则安装 {name}.veb；或者，如果只存在带版本号的 VEB，则安装唯一的 {name}-{version}.veb。请参阅选择版本。

扩展以 .veb（VillageSQL 扩展包）文件的形式分发，其中包含编译后的库和元数据。

选择版本

veb_dir 中的 VEB 文件可以命名为 {name}.veb（不带版本号）或 {name}-{version}.veb（带版本号）。要安装特定的带版本号 VEB，请添加 VERSION 子句：

INSTALL EXTENSION vsql_uuid VERSION '0.2.0';

使用 VERSION 时，服务器会打开 vsql_uuid-0.2.0.veb，并验证其 manifest.json 中的版本是否与 0.2.0 匹配。不使用 VERSION 时，服务器按如下方式解析文件：

如果 {name}.veb 存在，则安装它；版本从其 manifest.json 中读取。
否则，如果恰好存在一个 {name}-{version}.veb，则安装它；文件名中的版本会与其 manifest.json 中的版本进行核对。
否则，安装失败，您必须指定一个版本。

如果存在多个带版本号的 VEB 且不存在不带版本号的 VEB，则 INSTALL EXTENSION 会失败并报错

Multiple versions of extension '<name>' found in '<dir>'; specify a version with INSTALL EXTENSION <name> VERSION 'x.y.z'

。请使用显式的 VERSION 子句重新运行。

扩展命名约定

VillageSQL 在不同的上下文中采用不同的命名约定：

SQL 命令： 使用下划线：INSTALL EXTENSION vsql_uuid
仓库名称： 使用连字符：github.com/villagesql/vsql-uuid
文件名： 使用下划线：vsql_uuid.veb
manifest.json： 使用下划线以匹配 SQL："name": "vsql_uuid"

示例：

# Clone from GitHub repo (hyphens in URL)
git clone https://github.com/villagesql/vsql-uuid

# But .veb file uses underscores
ls vsql_uuid.veb

# Install with underscores (no quotes)
INSTALL EXTENSION vsql_uuid;

所需权限

INSTALL EXTENSION、UNINSTALL EXTENSION 和 ALTER EXTENSION 受 EXTENSION_ADMIN 动态权限保护。这些语句会将本机扩展代码加载到正在运行的服务器中，因此它们需要管理权限，非特权账户无法使用。 EXTENSION_ADMIN 是在全局范围（ON *.*）授予的动态权限：

GRANT EXTENSION_ADMIN ON *.* TO user@host;

为了向后兼容，SUPER 也被接受作为后备权限，因此已持有 SUPER 的账户无需单独授权即可运行这些语句。由 --initialize 或 --initialize-insecure 创建的数据目录会直接将 EXTENSION_ADMIN 授予 root@localhost，因此新服务器无需手动授权。就地升级现有数据目录时，每个持有 SUPER 的用户账户都会被授予 EXTENSION_ADMIN — 但仅当没有任何账户已持有该权限时才会如此，因此已升级过一次的服务器在以后的升级中不会再次回填。保留的 mysql.* 系统账户被排除在外。两种权限都不具备的账户会在任何扩展工作开始之前被拒绝：

ERROR 1227 (42000): Access denied; you need (at least one of) the EXTENSION_ADMIN or SUPER privilege(s) for this operation

以同样的方式撤销该权限：

REVOKE EXTENSION_ADMIN ON *.* FROM user@host;

撤销会立即生效，而不是在下次连接时生效。服务器会在每条扩展 DDL 语句上对照账户的当前授权检查 EXTENSION_ADMIN/SUPER，因此现有会话在撤销后不会保留该权限 — 它的下一条语句就会失败，并报出上面显示的相同 ERROR 1227 (42000)。

先决条件

正在运行的 VillageSQL Server 实例
管理员权限（root 或同等权限）

安装内置扩展

与 VillageSQL 一起提供的内置扩展已位于 veb_dir 中。只需启用它们：

-- Connect to VillageSQL
mysql -u root -p

-- Install the extension
INSTALL EXTENSION vsql_complex;

验证安装

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

输出：

+----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+
| EXTENSION_NAME | EXTENSION_VERSION | PENDING_VERSION | PENDING_REQUESTED_AT | PENDING_LAST_ERROR | PENDING_LAST_ERROR_AT |
+----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+
| vsql_complex   | 0.0.1             | NULL            | NULL                 | NULL               | NULL                  |
+----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+

测试功能

-- Create a database first
CREATE DATABASE test_db;
USE test_db;

-- Test extension functions
CREATE TABLE test (id INT, value COMPLEX);
INSERT INTO test VALUES (1, '(3,4)');
SELECT complex_abs(value) FROM test;  -- Returns 5.0

-- Clean up
DROP TABLE test;
DROP DATABASE test_db;

安装外部扩展

对于单独下载或构建的扩展：

在安装外部扩展之前，您的服务器必须配置 veb_dir。请参阅配置 veb_dir。

1. 复制 .veb 文件

找到服务器的扩展目录，然后将 .veb 文件复制到其中：

-- Find the extension directory
SHOW VARIABLES LIKE 'veb_dir';

cp /path/to/my_extension.veb /path/to/veb_dir/

2. 安装扩展

INSTALL EXTENSION my_extension;

要固定预期的版本（在 CI 或脚本化的部署中很有用），请包含 VERSION 子句：

INSTALL EXTENSION my_extension VERSION '1.2.0';

如果清单报告的版本不同，则安装失败，并且不会注册任何内容：

ERROR 3219 (HY000): Cannot install extension 'my_extension': manifest version
is '0.0.1' but VERSION '1.2.0' was specified

这是后备文件路径（不存在 {name}-{version}.veb）— 它与前面显示的 Version mismatch in '<file>' 错误属于不同的代码路径，后者在带版本号的文件本身存在时触发。

3. 验证安装

SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'my_extension';

故障排除

问题	解决方案
`Extension not found`	验证 `.veb` 文件是否位于 `veb_dir` 中：`SHOW VARIABLES LIKE 'veb_dir'`
`Permission denied`	检查文件权限：`chmod 644 extension.veb`
`extension name mismatch`	扩展的内部名称与 `.veb` 文件名不匹配。重新构建扩展。
`vef_register not found: ...`	`.veb` 文件未导出有效的 VEF 入口点。使用正确的 SDK 重新构建。
`vef_register returned an error: ...`	扩展注册失败。阅读附加的消息以获取详细信息。
`Cannot install extension 'name': manifest version is 'X' but VERSION 'Y' was specified`	`VERSION` 子句选择了 `{name}-{version}.veb`，但其内部清单报告了不同的版本。请使用清单中的版本重新运行，或修正文件名。
`Multiple versions of extension 'name' found in '<dir>'; specify a version with INSTALL EXTENSION name VERSION 'x.y.z'`	存在多个 `{name}-{version}.veb` 文件，但没有不带版本号的 `{name}.veb`。请使用显式的 `VERSION` 子句重新运行。

有关更多故障排除信息，请参阅管理扩展。

后续步骤

管理扩展

监控和排除已安装扩展的故障

可用扩展

浏览您可以安装的扩展

创建扩展

构建您自己的扩展

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

命令语法

选择版本

扩展命名约定

所需权限

先决条件

安装内置扩展

验证安装

测试功能

安装外部扩展

1. 复制 .veb 文件

2. 安装扩展

3. 验证安装

故障排除

后续步骤

管理扩展

可用扩展

创建扩展

​命令语法

​选择版本

​扩展命名约定

​所需权限

​先决条件

​安装内置扩展

​验证安装

​测试功能

​安装外部扩展

​1. 复制 .veb 文件

​2. 安装扩展

​3. 验证安装

​故障排除

​后续步骤

管理扩展

可用扩展

创建扩展

命令语法

选择版本

扩展命名约定

所需权限

先决条件

安装内置扩展

验证安装

测试功能

安装外部扩展

1. 复制 .veb 文件

2. 安装扩展

3. 验证安装

故障排除

后续步骤