Working with modules

Modules are WebAssembly extensions that add functions to the database. This page shows the command-line workflow for a Surrealism module: scaffold a project, build it, inspect the result, and run a function before you deploy it.

mod is the launcher's component for this work, and it is the intended home of these commands. Its first release is not published yet, so surreal install mod does not work today. Until it is, the same commands are available from the database component as surreal db module, and the examples below use that form. The top-level surreal module form is deprecated and prints a warning.

Create a module project

surreal db module init my-module

init scaffolds a Rust project with a surrealism.toml and a starter src/lib.rs. It asks for the organisation and module name interactively. In a script, add --headless with --org, and --name when the module should not take the folder's name.

surreal db module init my-module --headless --org acme --name my-module

Build the module

Run build from the project folder, or name the source folder.

surreal db module build
surreal db module build ./my-module --out my-module.wasm

A build is a release build. Add --debug for a debug build.

Inspect and run it

info shows the module's information, and sig shows the signature of one of its functions.

surreal db module info my-module.wasm
surreal db module sig my-module.wasm --fnc greet

run calls a function with arguments, without a database. Repeat --arg for each argument.

surreal db module run my-module.wasm --fnc greet --arg "World"

Use the module in a database

Define the built file in a database with DEFINE MODULE and call its functions from SurrealQL. The Surrealism guides cover writing the functions, the attribute reference and deployment.

Reference

The command reference is surreal db module today, and the modules page in the CLI reference explains how it relates to surreal mod.