> ## 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` クレートを使って Rust で書けます。SDK がすべての FFI マーシャリングを処理します。あなたは通常の Rust を書き、`extension!` マクロが、サーバーがロード時に呼び出す C のエントリポイントを生成します。

## Rust を選ぶべき場面

次の場合、Rust が正しい選択です。

* Rust を好み、C++ のコードベースを必要としない
* ガベージコレクタなしでメモリ安全性が欲しい
* 新しい拡張機能を構築しており、既存の C++ 依存関係がない

既存の C++ コードベースがある場合、または現時点で最も完全なカスタム型ビルダー API が必要な場合は、[C++ 拡張機能の作成](https://villagesql.com/docs/ja/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
```

## 新しいクレートのセットアップ

ライブラリクレートを作成し、SDK を追加して、設定します。

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

次に `Cargo.toml` でクレートの種類を設定します。

```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/ja/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/ja/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/ja/extensions/build/rust-sdk.md) — ROT-13 の例、パッケージング、およびテストの詳細を含む完全な手順
* [Rust のカスタム型](https://villagesql.com/docs/ja/sdk/rust/custom-types.md) — バイナリ格納と順序付けを備えた新しい列型の定義
* [Rust API リファレンス](https://villagesql.com/docs/ja/sdk/rust/api-reference.md) — InValue、VdfReturn、およびすべてのマクロ
* [C++ 拡張機能の作成](https://villagesql.com/docs/ja/guides/cpp-extensions.md) — 同じ作業の C++ での手順


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