Surrealism extensions are written in Rust, compiled into .surli archives, 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, custom case conversions, or quantitative finance.
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 ext initcommand to begin a new project. This command works in a similar manner tocargo newin scaffolding a new project with its owntomlfile (package.toml).Annotate functions to export with
#[surrealism].Use the
surreal ext buildcommand to build the extension, and optionallysurreal ext signto sign it.In SurrealDB, allow access to the archive and define the extension to access the functions.
What is available in Surrealism
Current Surrealism releases include:
function-level metadata such as
commentvia#[surrealism(...)], and read-only or read-write database access through aTransactionparameter;one-time initialisation with
#[surrealism(init)], run when the extension is built;namespaced exports with
#[surrealism] mod ...;optional read-only attached filesystem data packaged into the archive;
signed archives, and capabilities granted per extension when it is defined;
server-side resource controls for execution time, memory, and the number of calls that run at once.
The next pages walk through the workflow and APIs:
More examples
Further examples - additional plugins to read through