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

# 编写 Rust 扩展

> 如何用 Rust 编写 VillageSQL 扩展 — 何时选择 Rust、cargo-vsql 设置、编写函数、测试和安装。

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

VillageSQL 扩展可以使用 `villagesql` crate 以 Rust 编写。SDK 处理所有 FFI 编组 — 您编写普通的 Rust 代码，`extension!` 宏会生成服务器在加载时调用的 C 入口点。

## 何时选择 Rust

在以下情况下，Rust 是正确的选择：

* 您更喜欢 Rust，并且不需要 C++ 代码库
* 您想要内存安全，但不想要垃圾回收器
* 您正在构建一个新扩展，并且没有现有的 C++ 依赖

如果您已有 C++ 代码库，或者需要目前最完整的自定义类型构建器 API，请参阅 [编写 C++ 扩展](https://villagesql.com/docs/zh/guides/cpp-extensions.md)。

> [!WARNING]
>
> 该 API 对于扩展开发是稳定的，但自定义类型构建器 API 仍在成熟中。

## 先决条件

您需要：

* **Rust stable 工具链** — 从 [rustup.rs](https://rustup.rs) 安装
* **cargo-vsql** — 用于打包、安装和测试的 Cargo 子命令

从 SDK 仓库安装 `cargo-vsql`：

```bash theme={null}
git clone https://github.com/villagesql/vsql-rust-sdk
cd vsql-rust-sdk
cargo install --path cargo-vsql
```

## 创建新 Crate

创建一个库 crate，添加 SDK，然后进行配置：

```bash theme={null}
cargo new --lib vsql_my_extension
cd vsql_my_extension
cargo add villagesql
```

然后在 `Cargo.toml` 中设置 crate 类型：

```toml theme={null}
[lib]
crate-type = ["cdylib"]
```

在 `Cargo.toml` 旁边添加 `manifest.json`：

```json theme={null}
{
  "name": "vsql_my_extension",
  "version": "0.1.0",
  "description": "My VillageSQL extension",
  "author": "Your Name",
  "license": "GPL-2.0"
}
```

## 编写函数

[用 Rust 构建扩展](https://villagesql.com/docs/zh/extensions/build/rust-sdk.md) 页面提供了带有 ROT-13 示例的完整演练。简短版本：实现 `fn(&[InValue]) -> VdfReturn`，用 `func!` 注册它，然后用 `extension!` 包装所有内容：

```rust theme={null}
use villagesql::{InValue, VdfReturn};

fn my_func_impl(args: &[InValue]) -> VdfReturn {
    match args.first() {
        Some(InValue::String(s)) => VdfReturn::string(s.to_uppercase()),
        Some(InValue::Null) | None => VdfReturn::null(),
        _ => VdfReturn::error("my_func: expected a STRING argument"),
    }
}

villagesql::extension! {
    funcs: [
        villagesql::func!(my_func_impl, "my_func", [villagesql::Type::String] -> villagesql::Type::String),
    ]
}
```

有关自定义类型（二进制存储、排序、哈希），请参阅 [Rust 中的自定义类型](https://villagesql.com/docs/zh/sdk/rust/custom-types.md)。

## 测试扩展

在 `mysql-test/t/basic.test` 中编写测试：

```sql theme={null}
INSTALL EXTENSION vsql_my_extension;
SELECT my_func('hello');
SELECT my_func(NULL);
UNINSTALL EXTENSION vsql_my_extension;
```

设置您的 VillageSQL 构建目录，生成预期结果，然后运行：

```bash theme={null}
export VillageSQL_BUILD_DIR=/path/to/villagesql/build
cargo vsql test --record
cargo vsql test
```

通过的运行会为每个测试文件打印 `[ pass ]`。

## 在 SQL 中安装

打包并安装：

```bash theme={null}
cargo vsql install
```

然后在 SQL 中：

```sql theme={null}
INSTALL EXTENSION vsql_my_extension;
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'vsql_my_extension';
SELECT my_func('hello');
-- → HELLO
```

## 另请参阅

* [用 Rust 构建扩展](https://villagesql.com/docs/zh/extensions/build/rust-sdk.md) — 带有 ROT-13 示例的完整演练、打包和测试细节
* [Rust 中的自定义类型](https://villagesql.com/docs/zh/sdk/rust/custom-types.md) — 定义带有二进制存储和排序的新列类型
* [Rust API 参考](https://villagesql.com/docs/zh/sdk/rust/api-reference.md) — InValue、VdfReturn 和所有宏
* [编写 C++ 扩展](https://villagesql.com/docs/zh/guides/cpp-extensions.md) — 完成同一任务的 C++ 路径


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.