Writing Rust Extensions

How to write a VillageSQL extension in Rust — when to choose Rust, cargo-vsql setup, writing a function, testing, and installing.

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples in this guide work on VillageSQL. Install Now →

VillageSQL extensions can be written in Rust using the villagesql crate. The SDK handles all FFI marshaling — you write ordinary Rust, and the extension! macro generates the C entry points the server calls at load time.

When to Choose Rust

Rust is the right choice when:

• You prefer Rust and don’t need a C++ codebase
• You want memory safety without a garbage collector
• You’re building a new extension and have no existing C++ dependency

If you have an existing C++ codebase or need the most complete custom-type builder API available today, see Writing C++ Extensions.

The Rust SDK is at version 0.0.1. The API is stable for extension development but the custom-type builder API is still maturing.

Prerequisites

You need:

• Rust stable toolchain — install at rustup.rs
• cargo-vsql — the Cargo subcommand for packaging, installing, and testing

Install cargo-vsql from the SDK repo:

git clone https://github.com/villagesql/vsql-rust-sdk
cd vsql-rust-sdk
cargo install --path cargo-vsql

Set Up a New Crate

Create a library crate and configure it:

cargo new --lib vsql_my_extension
cd vsql_my_extension

Edit Cargo.toml:

[package]
name = "vsql_my_extension"
version = "0.1.0"
edition = "2021"

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

[dependencies]
villagesql = "0.0.1"

Add manifest.json alongside Cargo.toml:

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

Write a Function

The Building Extensions in Rust page has the full walkthrough with the ROT-13 example. The short version: implement fn(&[InValue]) -> VdfReturn, register it with func!, and wrap everything in extension!:

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),
    ]
}

For custom types (binary storage, ordering, hashing), see Custom Types in Rust.

Test Your Extension

Write a test in mysql-test/t/basic.test:

INSTALL EXTENSION vsql_my_extension;
SELECT my_func('hello');
SELECT my_func(NULL);
UNINSTALL EXTENSION vsql_my_extension;

Set your VillageSQL build directory, generate expected results, then run:

export VillageSQL_BUILD_DIR=/path/to/villagesql/build
cargo vsql test --record
cargo vsql test

A passing run prints [ pass ] for each test file.

Install in SQL

Package and install:

cargo vsql install

Then in SQL:

INSTALL EXTENSION vsql_my_extension;
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'vsql_my_extension';
SELECT my_func('hello');
-- → HELLO

See also

• Building Extensions in Rust — full walkthrough with the ROT-13 example, packaging, and testing details
• Custom Types in Rust — define new column types with binary storage and ordering
• Rust API Reference — InValue, VdfReturn, and all macros
• Writing C++ Extensions — the C++ path for the same task