vsql-extension-template-rust

A cargo-generate template for building VillageSQL extensions in Rust.

Prerequisites

• Rust toolchain (stable)
• cargo-generate 0.18 or higher (the template declares this floor and older versions refuse to run it)
• A completed VillageSQL build, for the install and test steps

cargo install cargo-generate

Usage

cargo generate gh:villagesql/vsql-extension-template-rust --name vsql_my_extension

cargo-generate will prompt for:

Prompt	Default	Description
Extension description	A VillageSQL extension	Populates Cargo.toml and manifest.json
Author name	—	Populates manifest.json
License	GPL-2.0	Populates Cargo.toml and manifest.json
SQL function name	—	The name of the initial SQL function (e.g. rot13, my_func)

What you get

vsql_my_extension/
├── .github/
│   └── workflows/
│       └── ci.yml          # fmt, clippy, audit, and cargo vsql test
├── Cargo.toml
├── manifest.json           # vsql extension manifest
├── rust-toolchain.toml     # pins stable toolchain with rustfmt + clippy
├── rustfmt.toml            # formatter config
├── src/
│   └── lib.rs              # starter STRING → STRING function
└── mysql-test/
    ├── suite.opt
    ├── t/
    │   └── vsql_my_extension.test
    └── r/
        └── vsql_my_extension.result

The generated src/lib.rs registers a working passthrough (identity) function under your chosen SQL function name. It compiles, passes cargo vsql test, and is ready to replace with your logic.

Developing your extension

Install cargo-vsql:

cargo install cargo-vsql

Build and run tests against a local VillageSQL server:

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

Record updated expected results after changing test queries:

cargo vsql test --record

See the cargo-vsql README and the villagesql SDK README for the full API.

CI

The generated workflow (.github/workflows/ci.yml) runs four jobs on every push and pull request:

Job	What it does
fmt	cargo fmt --check
clippy	cargo clippy -- -D warnings
audit	cargo audit via rustsec/audit-check
test	Builds, runs cargo vsql test against the VillageSQL dev server, and uploads the .veb artifact

The test job uses villagesql/extension-actions/rust and requires the actions: read permission to download the dev server artifact from villagesql/villagesql-server.

Examples

The vsql-rust-sdk examples show what a complete extension looks like:

• vsql_rot13 — minimal string function
• vsql_rational — custom SQL type with arithmetic functions