Working with extensions

Extensions are WebAssembly packages that add functions to the database. This page shows the command-line workflow for a Surrealism extension: scaffold a project, build it, inspect the result, run a function, then sign and install it. Extensions were called modules before SurrealDB 4.0, when the commands below were surreal db module commands, part of the database.

The commands belong to ext, the extension component of the Surreal CLI, run as surreal ext. Its first release is not published yet, so surreal install ext does not work today.

Create a project

surreal ext init my-extension

init scaffolds a Rust project with a package.toml and a starter src/lib.rs. It asks for the organisation and extension name interactively. In a script, add --headless with --org, and --name when the extension should not take the folder's name.

surreal ext init my-extension --headless --org acme --name my-extension

Build the extension

Run build from the project folder, or name the source folder. The archive is named after the organisation, name and version in package.toml unless --out names it.

surreal ext build
surreal ext build ./my-extension --out my-extension.surli

A build is a release build. Add --debug for a debug build.

Inspect and run it

info lists the functions the archive exports, and sig shows the signature of one of them.

surreal ext info my-extension.surli
surreal ext sig --fnc greet my-extension.surli

run calls a function with arguments, without a database. Repeat --arg for each argument, written as a SurrealQL value.

surreal ext run --fnc greet --arg '"World"' my-extension.surli

Sign and install it

To let others check where an archive came from, name a signer in package.toml, build again, and sign the archive:

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

Place the archive in a bucket of the database, then install it. install shows the signer, the digest and the capabilities the extension requests, asks which to accept, and defines it:

surreal ext install 'f"extensions:/my-extension.surli"' --as greeting \
    -e ws://localhost:8000 -u root -p secret --ns app --db main

The extension's functions are then called from SurrealQL as ext::greeting::greet('World'). DEFINE EXTENSION defines an extension directly, and the Surrealism guides cover writing the functions and the attribute reference.

Reference

The command reference is surreal ext.