> ## 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 添加新功能。

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

## 命令语法

```sql theme={null}
INSTALL EXTENSION extension_name;
```

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

<h3 id="extension-naming-conventions">
  扩展命名约定
</h3>

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

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

**示例：**

```bash theme={null}
# 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` 中。只需启用它们：

```sql theme={null}
-- Connect to VillageSQL
mysql -u root -p

-- Install the extension
INSTALL EXTENSION vsql_complex;
```

### 验证安装

```sql theme={null}
-- List installed extensions
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```

**输出：**

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

### 测试功能

```sql theme={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;
```

## 安装外部扩展

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

<Info>
  在安装外部扩展之前，您的服务器必须配置 `veb_dir`。请参阅 [配置 veb\_dir](/docs/zh/mysql-8.4/0.0.4/managing#configuring-veb_dir)。
</Info>

### 1. 复制 .veb 文件

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

```sql theme={null}
-- Find the extension directory
SHOW VARIABLES LIKE 'veb_dir';
```

```bash theme={null}
cp /path/to/my_extension.veb /path/to/veb_dir/
```

### 2. 安装扩展

```sql theme={null}
INSTALL EXTENSION my_extension;
```

### 3. 验证安装

```sql theme={null}
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: ...` | 扩展注册失败。阅读附加的消息以获取详细信息。                                       |

有关更多故障排除信息，请参阅 [管理扩展](/docs/zh/mysql-8.4/0.0.4/managing)。

## 后续步骤

<CardGroup cols={2}>
  <Card title="管理扩展" icon="sliders" href="/docs/zh/mysql-8.4/0.0.4/managing">
    监控和排除已安装扩展的故障
  </Card>

  <Card title="可用扩展" icon="list" href="/docs/zh/extensions">
    浏览您可以安装的扩展
  </Card>

  <Card title="创建扩展" icon="code" href="/docs/zh/mysql-8.4/0.0.4/create">
    构建您自己的扩展
  </Card>
</CardGroup>