Skip to content

Guides

Creating custom extensions

This page walks you through the options available when building an extension from scratch. Extensions were called Surrealism modules before SurrealDB 4.0, and the commands below were surreal db module commands.

You need a recent Rust toolchain, the wasm32-wasip2 target, and the Surreal CLI with its ext component, which runs as surreal ext. From SurrealDB 4.0, the database executable no longer builds extensions: surreal db extension and the other earlier spellings only print where the commands have moved.

rustup target add wasm32-wasip2

To run the extension, you also need a SurrealDB server, which you can install from the installation guide.

The fastest way to start is surreal ext init:

surreal ext init

This creates the project scaffold (Cargo.toml, package.toml, .cargo/config.toml and src/lib.rs) ready for extension builds.

From SurrealDB 4.0, the tokio_unstable flag in .cargo/config.toml is commented out. Uncomment it only when a dependency needs Tokio's net feature, such as a Tokio-based HTTP client:

.cargo/config.toml
[build]
rustflags = ["--cfg", "tokio_unstable"]

In SurrealDB 3.3 and earlier, the flag is always set.

An HTTP client built on the wasi:http interface, such as waki, needs no Tokio flag. From SurrealDB 4.0 the host provides wasi:http, and each request is held to the extension's net grant. See CAPABILITIES.

To automatically set the name and organisation for a project, you can use the following flags:

surreal ext init --headless --org surrealdb --name my_surreal_extension ./my_surreal_extension

Create a new library crate for your extension:

cargo new --lib my_surreal_extension
cd my_surreal_extension

Configure the library as a dynamic WASM library and add the extension SDK plus any other crates you need to Cargo.toml, following versions recommended for your SurrealDB release:

[lib]
crate-type = ["cdylib"]

For a full annotated example, follow the quick tutorial.

Add a package.toml file at the crate root next to Cargo.toml. Before SurrealDB 4.0 the file was called surrealism.toml, which is still read when there is no package.toml. surreal ext config reads and changes the file from the command line.

A minimal example:

target = "rust"
abi = 5

[package]
organisation = "surrealdb"
name = "demo"
version = "1.0.0"

[capabilities]
allow_scripting = true
allow_arbitrary_queries = true
allow_write = false
allow_functions = ["fn::test"]
allow_net = ["127.0.0.1:8080"]

Optional attached filesystem:

[attach]
fs = "fs"

The [capabilities] section is a request. It is shown when the extension is installed, and the extension receives only what its definition grants. See CAPABILITIES.

When [attach] fs = "fs" is present, the fs/ folder in your project is packed into the archive as a read-only filesystem available to the extension at runtime.

surreal ext build writes the abi value itself, so the number in your file has no effect on the archive.

A [bindings] table declares values that the extension reads by name and that each database gives it when it defines the extension, such as an API key. Each entry gives a SurrealQL type, either alone or in a table with a description and a sensitive flag:

[bindings]
api_key = { type = "string", description = "Mailgun API key", sensitive = true }
author = "option<string>"

A definition must give an expression for every name whose type is not option<...>, in its BINDINGS clause. Mark a name sensitive when its value is a secret: surreal ext install then warns if the value is given as a literal, which INFO and exports would show. The extension reads a value with surrealism::binding(), described in Reading bindings.

Expose functions to SurrealQL by annotating them with #[surrealism]. Only functions you mark this way are included in the extension and callable from the database.

use surrealism::{surrealism, Transaction};

#[surrealism]
fn can_drive(age: i64) -> bool {
    age >= 18
}

#[surrealism(comment = "Counts the records in a table")]
async fn count_records(tx: Transaction, table: String) -> anyhow::Result<i64> {
    tx.sql_with_vars("count(SELECT * FROM type::table($table))", [("table", table)]).await
}

The tx parameter gives the function read-only access to the database inside the calling query's transaction. A function that needs to write takes Transaction<ReadWrite> instead. This form is available from SurrealDB 4.0; earlier versions use #[surrealism(writeable)] and the free function surrealism::sql().

For the full attribute reference (database access, comment, init, and namespaced Rust modules), see extension attribute reference.

From your project directory, compile to a .surli artefact with the Surreal CLI:

surreal ext build --out demo.surli .

For faster local iteration, use debug builds. This works in the same way as cargo build --debug in skipping optimisation passes to speed up compiling time in exchange for lower performance.

surreal ext build --debug --out demo.surli .

See the surreal ext reference for all flags.

A signed archive lets whoever installs it check that it came from you. Name the signer in package.toml, build again so that the signer is part of the archive, then sign it. With an SSH key:

surreal ext config signer ssh ~/.ssh/release.pub
surreal ext build --out demo.surli .
surreal ext sign --key ~/.ssh/release demo.surli

For Sigstore keyless signing from CI, name the workflow instead, with surreal ext config signer github --repo <owner/name> --workflow <file>, and run surreal ext sign demo.surli in that workflow. An extension that you build and load yourself does not need a signature, and is defined as UNSIGNED.

Place the .surli file in a bucket that the database can read, then define it with DEFINE EXTENSION, or install it with surreal ext install, which checks the signer and asks which requested capabilities to grant.

DEFINE EXTENSION ext::demo FROM f"extensions:/demo.surli" UNSIGNED;

Connect with the CLI, SurrealDB Studio, or an SDK and invoke your functions from SurrealQL. Confirm return values and error handling match what you expect.

If something fails:

  • verify that experimental capabilities include surrealism;

  • verify the extension was rebuilt after source changes, and defined again with DEFINE EXTENSION OVERWRITE, since the definition pins the archive's digest;

  • verify that the definition grants the capabilities the function needs, such as write for a function that takes Transaction<ReadWrite>;

  • verify your SurrealDB build supports the targeted extension ABI.

For a high-level picture of how these steps fit together, see the extension overview.

Was this page helpful?

Last updated