Surrealism modules are ordinary Rust crates that compile to a WebAssembly (WASM) binary. The build embeds metadata about each #[surrealism] function so SurrealDB can map SurrealQL calls to the correct exports without recompiling the database. You keep your business logic in Rust; SurrealDB ships the runtime that loads and executes the WASM.
WASM target and sandbox
The compiler targets WASM so your code runs inside SurrealDB’s WebAssembly runtime, not as a native library on the host. That boundary is the sandbox: memory, execution time, and host capabilities are constrained by the engine, which reduces the blast radius of untrusted or buggy extension code compared with loading raw shared objects.
Interaction with the engine
The WASM module does not link directly into SurrealDB’s core. Instead, the engine loads the binary, resolves exports, and marshals values between SurrealQL and your Rust functions through the Surrealism ABI. You work with SurrealDB’s types and APIs exposed by the SDK rather than arbitrary process memory. The same SurrealDB binary can load different modules over time; only the WASM you install and register determines which extension functions exist in a given environment.
Lifecycle
The end-to-end lifecycle is: compile the crate with surreal module, upload the .wasm into storage (typically via DEFINE BUCKET), define the module so functions are registered (DEFINE MODULE), then invoke those functions from queries. Operational teams often automate upload and definition in CI so test and production databases stay aligned. The overview summarises this flow in one place.
Security
Treat every module as privileged code that can affect data your database can access. Sandboxing limits host access, but a module can still implement logic that leaks or corrupts data if you expose it to the wrong scopes. Load only WASM you trust, pin versions, and follow least privilege for namespaces, databases, and credentials that call into Surrealism functions.