GitHub - villagesql/vsql-rust-sdk: Write VillageSQL extensions in safe Rust: the SDK crate, the cargo-vsql packaging tool, and FFI bindings

Write custom SQL functions (VDFs) for VillageSQL in safe Rust. The SDK handles all FFI marshaling so you work entirely in ordinary Rust types.

Docs: VillageSQL documentation · Writing Rust extensions · Install VillageSQL Server

Crates

Crate	Description
`villagesql`	Safe Rust SDK for writing VDF extension functions
`cargo-vsql`	Cargo subcommand for packaging and testing extensions
`villagesql-sys`	Raw FFI bindings (used internally by `villagesql`)

Prerequisites

Rust toolchain (stable, 1.87+)
cargo-vsql installed (see cargo-vsql README)
VillageSQL build directory (for install and test commands)

Quick start

1. Install cargo-vsql

2. Create a new extension crate

The fastest way is the vsql-extension-template-rust template — it scaffolds the Cargo.toml, manifest.json, source layout, and a CI workflow for you:

cargo install cargo-generate
cargo generate --git https://github.com/villagesql/vsql-extension-template-rust

Or set it up by hand

cargo new --lib my-extension
cd my-extension
cargo add villagesql

Then add to Cargo.toml, so Cargo builds a shared library the server can load:

[lib]
crate-type = ["cdylib"]

3. Write your function

use villagesql::{InValue, VdfReturn};

fn my_func(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, "my_func", [villagesql::Type::String] -> villagesql::Type::String),
    ]
}

4. Add a manifest

Create manifest.json next to Cargo.toml:

{
  "name": "my-extension",
  "version": "0.1.0",
  "description": "What your extension does",
  "author": "Your Name",
  "license": "GPL-2.0"
}

5. Package, install, and test

Run cargo vsql commands from inside your extension directory (not the workspace root).

export VillageSQL_BUILD_DIR=/path/to/villagesql/build
cargo vsql install
cargo vsql test

For the full API reference see the villagesql README. For all cargo vsql commands see the cargo-vsql README.

Continuous integration

Reusable GitHub Actions workflows for building, testing, and packaging Rust VillageSQL extensions live in villagesql/extension-actions. The vsql-extension-template-rust template wires them up by default.

Examples

examples/vsql_rot13 — minimal string function; a good starting template
examples/vsql_rational — custom type (n/d rational numbers) with arithmetic VDFs, demonstrating custom_type!, InValue::Custom, and VdfReturn::binary