module

Available since: v3.0.0

Manage and execute WASM modules, including Surrealism plugin modules: scaffold a project, build it, inspect the result, and run its functions from the command line, using the installed surreal CLI.

Usage

surreal db module [OPTIONS] <COMMAND>

Note

A dedicated mod component of the launcher will supersede surreal db module. Until it is released, surreal db module is the way to work with modules from the command line. The top-level form, surreal module, is deprecated and prints a warning that names surreal db module.

Subcommand	Purpose
`surreal db module init`	Initialise a new Surrealism module project.
`surreal db module build`	Build a WASM module.
`surreal db module run`	Run a function with arguments.
`surreal db module sig`	Show the function signature.
`surreal db module info`	Show the module information.
`surreal db module help`	Print this message or the help of the given subcommand.

surreal db module init

Scaffold a new Surrealism module project (Rust crate, surrealism.toml, .cargo/Config.toml, and starter src/lib.rs).

Usage

surreal db module init [OPTIONS] [PATH]

Arguments

Name	Description
`[PATH]`	Directory to scaffold the crate in. The current directory is used when omitted.

Options

Name	Description
`--headless`	Scaffold without prompting, for use in scripts and CI.
`--org<ORG>`	Organisation the module belongs to.
`--name<NAME>`	Name of the module.

surreal db module init

surreal db module init writes the WASI build flags Surrealism needs into .cargo/config.toml. surreal db module build applies the same flags when it invokes Cargo, so existing projects pick them up even if the file was not scaffolded yet.

.cargo/Config.toml flags

[build]
rustflags = ["--cfg", "tokio_unstable"]

For scripts or CI, use non-interactive mode:

surreal db module init --headless --org surrealdb --name my_module ./path/to/crate

surreal db module build

Build a WASM binary from the Rust source code. A binary must have the .surli file extension.

Usage

surreal db module build [OPTIONS] [PATH]

Arguments

Name	Description
`[PATH]`	Path to the crate to build. The current directory is used when omitted.

Options

Name	Description
`-o<FILE>`	Path of the `.surli` binary to write.
`--debug`	Skip the usual optimisation pass for a faster build time in exchange for lower performance.

surreal db module build -o demo.surli ../demo

Using --debug skips the usual optimisation pass for a faster build time in exchange for lower performance. Recommended when iterating and testing before producing a final build.

surreal db module build --debug -o demo-debug.surli .

surreal db module run

Run a single function from a compiled module, including functions that require arguments to be passed in.

Usage

surreal db module run [OPTIONS] --fnc <FUNCTION> <FILE>

Arguments

Name	Description
`<FILE>` required	Path to the compiled `.surli` module.

Options

Name	Description
`--fnc<FUNCTION>` required	Name of the function to run.
`--arg<ARG>`	Value passed to the function. Functions that take no arguments need no `--arg`.

surreal db module run --fnc can_drive --arg 17    demo.surli
surreal db module run --fnc can_drive --arg 18    demo.surli
surreal db module run --fnc result    --arg false demo.surli
surreal db module run --fnc result    --arg true  demo.surli
surreal db module run --fnc test_kv               demo.surli
surreal db module run --fnc test_io               demo.surli
surreal db module run --fnc test_none_value       demo.surli

surreal db module sig

Show the signature for a single function in a compiled module.

Usage

surreal db module sig [OPTIONS] --fnc <FUNCTION> <FILE>

Arguments

Name	Description
`<FILE>` required	Path to the compiled `.surli` module.

Options

Name	Description
`--fnc<FUNCTION>` required	Name of the function whose signature is shown.

surreal db module sig --fnc can_drive demo.surli

surreal db module info

Show the information held by a compiled WASM binary.

Usage

surreal db module info [OPTIONS] <FILE>

Arguments

Name	Description
`<FILE>` required	Path to the compiled `.surli` module.

surreal db module info demo.surli

Command help

To see the help information and usage instructions, in a terminal run the surreal db module --help command without any further arguments. This output lists subcommands, global options, and shared logging flags for the module command.

surreal db module --help

The output of the above command:

Manage and execute WASM modules

Usage: surreal module [OPTIONS] <COMMAND>

Commands:
  init   Initialize a new Surrealism module project
  run    Run a function with arguments
  sig    Show the function signature
  info   Show the module information
  build  Build a WASM module
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Logging:
  -l, --log <LOG>                              The logging level for the command-line tool [env: SURREAL_LOG=] [default: info] [possible values: none, full, error, warn, info, debug, trace]
      --log-format <LOG_FORMAT>                The format for terminal log output [env: SURREAL_LOG_FORMAT=] [default: text] [possible values: text, json]
      --log-socket <LOG_SOCKET>                Send logs to the specified host:port [env: SURREAL_LOG_SOCKET=]
      --log-file-level <LOG_FILE_LEVEL>        Override the logging level for file output [env: SURREAL_LOG_FILE_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-otel-level <LOG_OTEL_LEVEL>        Override the logging level for OpenTelemetry output [env: SURREAL_LOG_OTEL_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-level <LOG_SOCKET_LEVEL>    Override the logging level for unix socket output [env: SURREAL_LOG_SOCKET_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-format <LOG_SOCKET_FORMAT>  The format for socket output [env: SURREAL_LOG_SOCKET_FORMAT=] [default: text] [possible values: text, json]
      --log-file-enabled                       Whether to enable log file output [env: SURREAL_LOG_FILE_ENABLED=]
      --log-file-path <LOG_FILE_PATH>          The directory where log files will be stored [env: SURREAL_LOG_FILE_PATH=] [default: logs]
      --log-file-name <LOG_FILE_NAME>          The name of the log file [env: SURREAL_LOG_FILE_NAME=] [default: surrealdb.log]
      --log-file-format <LOG_FILE_FORMAT>      The format for log file output [env: SURREAL_LOG_FILE_FORMAT=] [default: text] [possible values: text, json]
      --log-file-rotation <LOG_FILE_ROTATION>  The log file rotation interval [env: SURREAL_LOG_FILE_ROTATION=] [default: daily] [possible values: daily, hourly, never]

surreal db module init

surreal db module build

surreal db module run

surreal db module sig

surreal db module info

Command help

Further reading