This guide walks you through building a Surrealism module from scratch: a Rust crate annotated for SurrealDB, compiled to WebAssembly, then registered in your database.
Prerequisites
You need a recent Rust toolchain (stable is fine) and the SurrealDB CLI (surreal) available on your PATH. Install SurrealDB from the installation guide if you have not already.
Create a Rust project
Create a new library crate for your module:
Configure the library as a dynamic WASM library and add the Surrealism SDK plus any other crates you need to Cargo.toml, following the versions recommended in the SurrealDB release notes for your SurrealDB 3.x version:
For dependency wiring and a full annotated example, follow the quick tutorial.
Configure surrealism.toml
Add a surrealism.toml file at the crate root next to Cargo.toml. It is required by the toolchain today; future releases will use it for richer metadata (for example, function versioning and capabilities). Until then, keep a minimal file so surreal module can run your build.
Annotate exported functions
Expose functions to SurrealQL by annotating them with #[surrealism]. Only functions you mark this way are included in the WASM module and callable from the database. Use ordinary Rust types that the Surrealism bindings support for your SurrealDB version.
Compile with surreal module
From your project directory, run the Surreal CLI to compile the module to a .wasm artefact (see the module command reference for flags and output paths). Resolve any compiler errors before continuing.
Load into SurrealDB
Upload the WASM file with DEFINE BUCKET so SurrealDB can store it, then register the exported functions with DEFINE MODULE. The exact names and paths must match how you referenced the bucket and module in your deployment.
Test your functions
Connect with the CLI, Surrealist, or an SDK and invoke your new functions from SurrealQL. Confirm return values and error handling match what you expect. If something fails, verify experimental Surrealism capabilities are enabled where your server requires them, and that the module version matches your database build.
For a high-level picture of how these steps fit together, see the Surrealism overview.