# Module architecture

How Surrealism modules are packaged, sandboxed, and invoked by SurrealDB, including exports metadata, runtime limits, and load strategy.

[Surrealism](/docs/learn/extensions/plugins/overview.md) 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](/docs/reference/cli/surrealdb-cli/environment-variables.md#surrealism-config).

## 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:

```bash
surreal start --lazy-surrealism
```

Or set:

```bash
SURREAL_LAZY_SURREALISM=true surreal start
```

## Lifecycle

The end-to-end lifecycle is: **build** your crate with [`surreal module`](/docs/reference/cli/surrealdb-cli/commands/module.md), **upload** the `.surli` archive (typically via [`DEFINE BUCKET`](/docs/reference/query-language/statements/define/bucket.md)), **define** the module ([`DEFINE MODULE`](/docs/reference/query-language/statements/define/module.md)), then **invoke** functions from queries.

Operational teams often automate upload and definition in CI so test and production databases stay aligned. The [overview](/docs/learn/extensions/plugins/overview.md) 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.