DEFINE MODULE

A DEFINE MODULE statement is used to define a module via which Surrealism extensions functions can be called.

Statement syntax

DEFINE MODULE [ OVERWRITE | IF NOT EXISTS ] @mod::@sub AS @file_name
	[ COMMENT @string ]

Example

A module includes a module and a sub, followed by a pointer to the .surli file containing the Rust code compiled to WASM through the Surrealism CLI.

DEFINE MODULE mod::test AS f"test:/demo.surli";

The keyword changed because everywhere else in SurrealQL AS introduces an alias, with the new name on the right. DEFINE MODULE read the other way round: the name on the left, the module's source on the right.

Once the module is defined, functions can be accessed through this path.

Assuming these two functions in the Rust code before compilation to WASM via the Surrealism CLI:

#[surrealism]
fn returns_true() -> bool { true };

#[surrealism]
fn check_num_size(num: i32) -> Result<i32, &'static str> {
    if num >= 500 {
        Err("Number is too big!")
    } else {
        Ok(num)
    }
}

They will then be accessible using the following paths.

RETURN mod::test::returns_true();
-- true

RETURN mod::test::check_num_size(100);
-- 100

The UNSIGNED keyword

UNSIGNED is required on every DEFINE MODULE statement, and its absence is a parse error. It sits at the end of the statement and can appear in any order alongside COMMENT and PERMISSIONS, because it reads as an option of the definition rather than a property of the executable.

DEFINE MODULE mod::color FROM f"modules:/color.surli" UNSIGNED COMMENT "Colour helpers";

The keyword marks a module as carrying no signature. Only packages published to Silo are signed — Silo signs a package when it is uploaded — so a module loaded from anywhere else can never carry one and must say so explicitly.

The requirement is in place before signature verification ships, so a definition written today stays valid once the keyword starts gating a real check. A module defined before 3.3.0 is treated as unsigned and keeps loading unchanged, and both INFO FOR DB and surreal export render the keyword back, so a dump re-imports.

Silo packages

A module can also be defined from a package published to Silo. This form is keyed by its package coordinates, so it takes no mod:: alias and no FROM:

DEFINE MODULE silo::surrealdb::color::<1.0.0> UNSIGNED;

The package is fetched over HTTPS from the configured Silo endpoint and cached, so you no longer need to build each module locally and upload the .surli file to a bucket before DEFINE MODULE can reach it.

Two databases that define the same package hold it separately, exactly as two databases using the same bucket object already do. A module keeps state between invocations, so this keeps that state inside the namespace and database that created it. REMOVE MODULE and DEFINE MODULE ... OVERWRITE therefore only evict the calling database's copy.