安装扩展

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

命令语法

INSTALL EXTENSION extension_name [VERSION 'version'];

提供 VERSION 时，服务器会打开 {name}-{version}.veb，将该版本与清单进行比较，如果两者不一致则中止安装。省略该子句则安装 {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;

先决条件

正在运行的 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 |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
+------------------+-------------------+

测试功能

-- 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): Version mismatch in 'my_extension-1.2.0.veb':
filename says '1.2.0' but manifest says '0.0.1'

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: ...`	扩展注册失败。阅读附加的消息以获取详细信息。
`Version mismatch in 'name-Y.veb': filename says 'Y' but manifest says 'X'`	`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. 验证安装

故障排除

后续步骤