Surrealism modules are Rust crates packaged as .surli archives. Each archive contains your compiled component plus metadata about exported #[surrealism] functions. SurrealDB reads this metadata to map SurrealQL calls to module exports without recompiling the database.
Component target and sandbox
Surrealism builds target WASI Preview 2 (wasm32-wasip2) and run through the WASM component model runtime. Your code does not execute as a native library on the host. The runtime boundary provides sandboxing where memory, execution time, filesystem access, and host capabilities can be constrained by server policy.
Interaction with the engine
The module does not link directly into SurrealDB’s core. Instead, the engine loads it in the Surrealism runtime, resolves exports, and marshals values between SurrealQL and your Rust functions through the Surrealism ABI. You work with SDK-exposed types and host imports, not arbitrary process memory.
At build time, Surrealism also extracts an exports manifest (names, argument types, return type, writeable flag, optional comment) and stores it in the archive. That allows metadata lookups without instantiating the module for every query-planning or introspection operation.
Runtime execution model
Surrealism uses pooled module controllers so invocations can reuse warm execution contexts instead of rebuilding runtime state for each call.
Pool ceiling: per-module controller pool size is capped by
SURREAL_SURREALISM_MAX_POOL_SIZE.Timeout mode: strict timeout behaviour can be configured by module/runtime settings.
Resource ceilings: memory, execution time, and module KV limits can be enforced with Surrealism environment variables.
For a complete list of server-level variables, see environment variables.
Module loading strategy
By default, SurrealDB eagerly compiles defined Surrealism modules at startup to reduce first-call latency. If you prefer lazy loading, start the server with:
Or set:
Lifecycle
The end-to-end lifecycle is: build your crate with surreal module, upload the .surli archive (typically via DEFINE BUCKET), define the module (DEFINE MODULE), then invoke functions from queries.
Operational teams often automate upload and definition in CI so test and production databases stay aligned. The overview summarises this flow.
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.