# Surrealism plugins

Surrealism is a plugin feature that allows users to compile Rust functions into modules that can be called from a SurrealDB instance.

Surrealism extensions are written in Rust, compiled into `.surli` modules, and loaded into a running SurrealDB instance. This gives you access to the Rust ecosystem while keeping extensions sandboxed within the database.

Surrealism was built in order to allow users to extend SurrealDB in ways that benefit them, without needing to make any changes to the code of SurrealDB itself. Some potential use cases are:

* Adding functions to create fake / mock data for testing.
* Accessing functionality in Rust crates that are too specific to merge into SurrealDB itself, such as [language-specific functionality](https://crates.io/crates/hangeul), [custom case conversions](https://docs.rs/convert_case/latest/convert_case/enum.Case.html), or [quantitative finance](https://docs.rs/crate/RustQuant/latest).
* Anything else you have built in your own code that you would like to access inside SurrealDB.

## How Surrealism works

Surrealism works by using the following steps:

* Use the [`surreal module init`](/docs/reference/cli/surrealdb-cli/commands/module.md) command to begin a new project. This command works in a similar manner to `cargo new` in scaffolding a new project with its own `toml` file (`surrealism.toml`).
* Annotate functions to export with `#[surrealism]`.
* Use the `surreal module build` command to build the module.
* In SurrealDB, [allow access to module files](/docs/reference/query-language/statements/define/bucket.md) and [define a module](/docs/reference/query-language/statements/define/module.md) to access the functions.

![A flowchart showing the steps involved to turn regular Rust code into a compiled WASM binary that can be accessed from a running SurrealDB instance.](~/assets/img/surrealdb/extension/surrealism_flow.png)

## What is available in Surrealism

Current Surrealism releases include:

* function-level metadata such as `writeable` and `comment` via `#[surrealism(...)]`;
* one-time module initialisation with `#[surrealism(init)]`;
* namespaced exports with `#[surrealism] mod ...`;
* optional read-only attached filesystem data packaged into the module archive;
* server-side resource controls for execution time, memory, and module KV limits.

The next pages walk through the workflow and APIs:

- [Quick tutorial](/docs/learn/extensions/plugins/quick-tutorial.md)
- [Creating custom modules](/docs/learn/extensions/guides/creating-custom-modules.md)
- [Surrealism attribute reference](/docs/learn/extensions/guides/surrealism-attribute-reference.md)