Rust API リファレンス

Rust SDK はアルファ版です。リリース間で破壊的な API 変更が発生する可能性があります。関数のみの拡張機能とカスタム型 (encode、decode、compare、hash) がサポートされています。集約、prerun()、VarArgs、システム変数とステータス変数、キーリングアクセス、および列ストレージ ABI は、現在 C++ のみです。これらのいずれかが必要な場合は、C++ SDK を使用してください。

このページは、villagesql クレート API のリファレンスです。入門チュートリアルについては、Rust で拡張機能を作成するを参照してください。カスタム型については、Rust のカスタム型を参照してください。

InValue

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

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 は、処理を続行することが安全でない場合に使用します。たとえば、保存されたデータが破損している場合や、内部の不変条件に違反している場合です。致命的なエラーは、ステートメント全体を中止します。

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 つ存在する必要があります。

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

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

func! マクロ

func! は、SQL で呼び出すことができる関数を宣言します。 4 つの形式 (パラメータなし、buffer_size のみ、deterministic のみ、両方):

villagesql::func!(rust_fn, "sql_name", [param_types] -> return_type)
villagesql::func!(rust_fn, "sql_name", [param_types] -> return_type, buffer_size: N)
villagesql::func!(rust_fn, "sql_name", [param_types] -> return_type, deterministic: true)
villagesql::func!(rust_fn, "sql_name", [param_types] -> return_type, buffer_size: N, deterministic: true)

buffer_size パラメータには、villagesql クレートの 0.0.2 以降が必要です。現在の crates.io リリース (0.0.1) ではこれを公開していません。 0.0.2 がリリースされるまでは、buffer_size を使用しない形式を使用してください。

引数	説明
`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")`。
`buffer_size: N`	オプション。文字列/バイナリの戻り値に対する結果バッファーのバイト単位のサイズ。サーバーのデフォルト (256 バイト) を使用するには `0` を指定します。関数が `buffer_size` より大きい文字列またはバイナリ値を返す場合、関数は切り捨てずにエラーになります。より大きな結果を処理するには、より大きな `buffer_size` を宣言してください。
`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 はオプションですが、推奨されます。

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! 宣言でカスタム型を参照します。

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 が必要です。

{
  "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 は失敗します。

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

InValue

VdfReturn

extension! マクロ

func! マクロ

custom_type! マクロ

custom! マクロ

manifest.json フィールド

​InValue

​VdfReturn

​extension! マクロ

​func! マクロ

​custom_type! マクロ

​custom! マクロ

​manifest.json フィールド

InValue

VdfReturn

extension! マクロ

func! マクロ

custom_type! マクロ

custom! マクロ

manifest.json フィールド