> ## 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 SDK API リファレンス

> VillageSQL Rust SDK の完全なリファレンス — InValue、VdfReturn、extension!、func!、custom_type!、および manifest.json フィールド。

<Note>
  Rust SDK はバージョン 0.0.1 です。
</Note>

このページは、`villagesql` クレート API のリファレンスです。 入門チュートリアルについては、[Rust で拡張機能を構築する](/docs/ja/mysql-8.4/0.0.4/rust-sdk) を参照してください。 カスタム型については、[Rust のカスタム型](/docs/ja/mysql-8.4/0.0.4/rust-custom-types) を参照してください。

## InValue

`InValue` は、サーバーが各関数の引数に対して渡す列挙型です。 関数は `args: &[InValue]` を受け取り、その値を使用する前に各引数をチェックする必要があります。

```rust theme={null}
pub enum InValue<'a> {
    String(&'a str),
    Real(f64),
    Int(i64),
    Null,
    Custom(&'a [u8]),
}
```

| バリアント           | Rust 型        | 対応する SQL 型                        |
| --------------- | ------------- | --------------------------------- |
| `String(&str)`  | UTF-8 文字列スライス | `STRING` / `VARCHAR` / `TEXT`     |
| `Real(f64)`     | 64 ビット浮動小数点数  | `REAL` / `DOUBLE` / `FLOAT`       |
| `Int(i64)`      | 64 ビット符号付き整数  | `INT` / `BIGINT` / `TINYINT`      |
| `Null`          | —             | 任意の型の SQL `NULL`                  |
| `Custom(&[u8])` | 生のバイナリバイト     | `custom_type!` を使用して登録された任意のカスタム型 |

常に `Null` を明示的にパターンマッチングしてください。 `.unwrap()` を呼び出すか、値のバリアントのみをパターンマッチングすると、バグになります。 SQL NULL はエラーではなく、通常の入力です。

## VdfReturn

`VdfReturn` は、関数がサーバーに返す値です。 関連する関数のいずれかを使用して構築します。

| コンストラクター                   | SQL 効果                                        |
| -------------------------- | --------------------------------------------- |
| `VdfReturn::null()`        | この行に対して SQL NULL を返します                        |
| `VdfReturn::string(s)`     | `String` 値を返します。 `s` は `impl Into<String>` です |
| `VdfReturn::real(v)`       | `f64` 値を返します                                  |
| `VdfReturn::int(v)`        | `i64` 値を返します                                  |
| `VdfReturn::binary(bytes)` | カスタム型の列のバイナリバイトを返します。 `bytes` は `Vec<u8>` です  |
| `VdfReturn::warning(msg)`  | この行に対して NULL を返し、SQL 警告を追加します。 実行は続行されます      |
| `VdfReturn::error(msg)`    | 致命的なエラーでステートメントを中止します                         |

**警告とエラー:**

`warning` は、残りの結果セットで処理を続けることが理にかなう、ユーザー入力の検証エラーに使用します。 厳密モードでは、MySQL は `INSERT` および `UPDATE` で警告をエラーに昇格させます。 `error` は、処理を続行することが安全でない場合に使用します。たとえば、保存されたデータを破損したり、内部の不変条件に違反したりする場合です。 致命的なエラーは、ステートメント全体を中止します。

```rust theme={null}
fn validate_impl(args: &[InValue]) -> VdfReturn {
    match args.first() {
        Some(InValue::Int(n)) if *n >= 0 => VdfReturn::int(*n),
        Some(InValue::Int(_)) => VdfReturn::warning("value must be non-negative"),
        Some(InValue::Null) | None => VdfReturn::null(),
        _ => VdfReturn::error("validate: expected an INT argument"),
    }
}
```

## extension! マクロ

`extension!` は、サーバーが VEB ファイルをロードするときに呼び出す VEF エントリポイントを生成します。 これは、クレート内に正確に 1 つ存在する必要があります。

```rust theme={null}
villagesql::extension! {
    funcs: [
        // One or more villagesql::func!(...) declarations
    ],
    types: [
        // One or more villagesql::custom_type!(...) declarations
    ]
}
```

どちらのセクションもオプションです。 純粋な関数拡張機能では `types:` を省略し、型のみの拡張機能では `funcs:` を省略します。 空の `extension!` ブロック (関数も型もなし) は有効ですが、何も行わない拡張機能が生成されます。

## func! マクロ

`func!` は、SQL で呼び出すことができる関数を宣言します。 位置引数:

```rust theme={null}
villagesql::func!(rust_fn, "sql_name", [param_types] -> return_type)
villagesql::func!(rust_fn, "sql_name", [param_types] -> return_type, deterministic: true)
```

| 引数                    | 説明                                                                                                              |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `rust_fn`             | VDF を実装する Rust 関数。 シグネチャ: `fn(&[InValue]) -> VdfReturn`。                                                        |
| `"sql_name"`          | SQL 関数名。 これは、ユーザーが SQL から呼び出す名前です。                                                                              |
| `[param_types]`       | カンマで区切られた `villagesql::Type::*` または `villagesql::custom!("name")` 値のリスト。 引数がない関数には `[]` を使用します。                 |
| `return_type`         | `villagesql::Type::*` または `villagesql::custom!("name")`。                                                        |
| `deterministic: true` | オプション。 関数が決定性を持つことを宣言します。つまり、同じ入力は常に同じ出力を生成し、副作用はありません。 オプティマイザーは、同じ入力に対して結果をキャッシュできます。 これは、それが真の場合にのみ設定してください。 |

`func!` で使用する **型定数**:

| `villagesql::Type::*`      | SQL 型    |
| -------------------------- | -------- |
| `villagesql::Type::String` | `STRING` |
| `villagesql::Type::Real`   | `REAL`   |
| `villagesql::Type::Int`    | `INT`    |

## custom\_type! マクロ

`custom_type!` は、新しい列タイプを登録します。 `type_name`、`persisted_length`、`max_decode_buffer_length`、`encode`、`decode`、および `compare` が必要です。 `hash` と `default` はオプションですが、推奨されます。

```rust theme={null}
villagesql::custom_type!(
    type_name: "sql_type_name",
    persisted_length: N,
    max_decode_buffer_length: M,
    encode: encode_fn,
    decode: decode_fn,
    compare: compare_fn,
    hash: hash_fn,
    default: "default_string",
)
```

| フィールド                      | 型                                        | 説明                                                                                                      |
| -------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `type_name`                | `&str` リテラル                              | SQL での型の名前。 SQL では大文字と小文字が区別されません。 すべてのインストールされた拡張機能で一意である必要があります。                                      |
| `persisted_length`         | `usize`                                  | ディスク上のストレージの固定バイト長。 エンコードされたすべての値は、正確にこの数のバイトを生成する必要があります。                                              |
| `max_decode_buffer_length` | `usize`                                  | デコードされた文字列の最大バイト長。 `decode` を呼び出す前に、出力バッファーのサイズを設定するために使用されます。                                          |
| `encode`                   | `fn(&str) -> Result<Vec<u8>, String>`    | `INSERT` 時期に呼び出されます。 SQL 文字列リテラルをバイナリに変換します。 入力を拒否するには、`Err(msg)` を返します。                                |
| `decode`                   | `fn(&[u8]) -> Result<String, String>`    | 値を表示するために呼び出されます。 バイナリを文字列に変換します。                                                                       |
| `compare`                  | `fn(&[u8], &[u8]) -> std::cmp::Ordering` | `ORDER BY`、`MIN`、`MAX` で呼び出されます。 `Less`、`Equal`、または `Greater` を返します。                                    |
| `hash`                     | `fn(&[u8]) -> usize`                     | オプション。 `COUNT(DISTINCT)` およびセット操作で呼び出されます。 `Equal` と比較される値は、同じハッシュ値を返す必要があります。 インデックス付きの列には推奨されます。      |
| `default`                  | `&str` リテラル                              | オプション。 サーバーが型を初期化するときに、コールバックが機能していることを確認するためにエンコードする有効な文字列。 正確に `persisted_length` バイトにエンコードする必要があります。 |

`default` フィールドは、列のデフォルト値ではありません。 これは、起動時のプローブです。 サーバーは、拡張機能をロードするときに `encode(default)` を呼び出して、コールバックが機能していることを確認します。 `encode` がデフォルトに対して `Err` を返す場合、拡張機能のロードは失敗します。

## custom! マクロ

`villagesql::custom!("type_name")` は、`func!` 宣言でカスタム型を参照します。

```rust theme={null}
villagesql::func!(
    my_fn,
    "my_sql_func",
    [villagesql::custom!("mytype")] -> villagesql::custom!("mytype"),
    deterministic: true
)
```

`villagesql::Type::*` がパラメータリストまたは戻り値の位置に表示される場所であれば、どこでも使用できます。 文字列は、対応する `custom_type!` で宣言された `type_name` と一致する必要があります。

## manifest.json フィールド

すべての拡張機能には、`Cargo.toml` の横に `manifest.json` が必要です。

```json theme={null}
{
  "name": "vsql_my_extension",
  "version": "0.1.0",
  "description": "Brief description of what the extension does",
  "author": "Your Name",
  "license": "GPL-2.0"
}
```

| フィールド         | 必須  | 形式                | 説明                                                                               |
| ------------- | --- | ----------------- | -------------------------------------------------------------------------------- |
| `name`        | はい  | 小文字の文字、数字、`_`、`-` | 拡張機能の識別子。 `INSTALL EXTENSION` 名と一致する必要があります。 SQL ではハイフンを使用すると、バッククォートで囲む必要があります。 |
| `version`     | はい  | MAJOR.MINOR.PATCH | セマンティックバージョン。                                                                    |
| `description` | いいえ | 文字列               | `INFORMATION_SCHEMA.EXTENSIONS` に表示されます。                                         |
| `author`      | いいえ | 文字列               | 著者名または組織。                                                                        |
| `license`     | いいえ | 文字列               | ライセンス識別子。 オープンソースの拡張機能には `GPL-2.0` を推奨します。                                       |

`name` の検証ルール: 文字で始まり、文字または数字で終わり、最大 64 文字。 マニフェストが無効な場合、`INSTALL EXTENSION` は失敗します。