surrealism

SurrealDB Surrealism WASM extension development. Write Rust functions, compile to WASM, deploy as database modules. Part of the surreal-skills collection.

Security Scan

The skill is an instruction-only walkthrough for writing and deploying SurrealDB WASM extensions with Rust; its instructions and requirements are coherent with that purpose and it does not request unexpected credentials or install arbitrary code.

Purpose & Capability

Name and description match the SKILL.md content: it documents writing Rust functions, compiling to WASM, and registering modules in SurrealDB. The prerequisites mentioned (Rust toolchain, WASM target, SurrealDB CLI) are appropriate and expected for this functionality.

Instruction Scope

Instructions are narrowly scoped to project files, building a WASM binary, and running SurrealDB CLI commands to register modules. The example shows using database credentials on the CLI (e.g., --user root --pass root) — this is relevant to registering modules but users should avoid using high-privilege credentials in production and be cautious about running or registering untrusted WASM modules.

Install Mechanism

No install spec or downloadable artifacts are present; the skill is instruction-only and does not cause any code to be fetched or written by the registry installer. This is the lowest-risk install footprint.

Credentials

The skill declares no required environment variables or secrets, and the only credentials referenced appear in a CLI example to access SurrealDB. Requesting DB credentials (for registering modules) is proportionate to the task; however the skill itself does not require or store them.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request persistent agent privileges or modify other skill configurations. Autonomous invocation is allowed by platform defaults but is not a special privilege granted by this skill.

Assessment

This skill is an instructional guide for building SurrealDB WASM extensions and appears internally consistent. Before using it: (1) only compile and deploy WASM modules from code you trust — WASM can execute arbitrary logic in your DB process; (2) avoid using high-privilege (root) DB credentials shown in examples; use least privilege and separate test environments; (3) install Rust and the SurrealDB CLI from official sources; (4) when registering modules, prefer storing WASM blobs in controlled buckets and review module code before enabling it in production. If you need higher assurance, verify the referenced upstream repository and rules document links and test the workflow in an isolated environment first.

Surrealism -- WASM Extensions for SurrealDB

New in SurrealDB 3. Write custom functions in Rust, compile them to WebAssembly (WASM), and deploy them as native database modules callable from SurrealQL.

Prerequisites

• Rust toolchain (stable) with wasm32-unknown-unknown target
• SurrealDB CLI v3.0.0+ (surreal binary with surreal module subcommand)
• Familiarity with SurrealQL DEFINE MODULE and DEFINE BUCKET

Development Workflow

1. Annotate   -- surrealism.toml + #[surrealism] on Rust functions
2. Compile    -- surreal module compile  (produces .wasm binary)
3. Register   -- DEFINE BUCKET + DEFINE MODULE in SurrealQL

Quick Start

# Create a new Surrealism project
cargo new --lib my_extension
cd my_extension

# Add the WASM target
rustup target add wasm32-unknown-unknown

# Create surrealism.toml (required manifest)
cat > surrealism.toml << 'TOML'
[package]
name = "my_extension"
version = "0.1.0"
TOML

# Write your extension (annotate with #[surrealism])
cat > src/lib.rs << 'RUST'
use surrealism::surrealism;

#[surrealism]
fn greet(name: String) -> String {
    format!("Hello, {}!", name)
}
RUST

# Compile to WASM using SurrealDB CLI
surreal module compile

# Register in SurrealDB
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

-- Grant access to the WASM file
DEFINE BUCKET my_bucket;

-- Register the module functions
DEFINE MODULE my_extension FROM 'my_bucket:my_extension.wasm';

-- Use the function in queries
SELECT my_extension::greet('World');

Use Cases

• Custom scalar functions callable from SurrealQL
• Fake/mock data generation for testing
• Domain-specific logic (language processing, quantitative finance, custom encoding)
• Access to niche Rust crate functionality too specific for core SurrealDB
• Custom analyzers for full-text search

Status

Surrealism is actively in development and not yet stable. The API may change between SurrealDB 3.x releases. File feedback via GitHub issues/PRs on the surrealdb/surrealdb repository.

Full Documentation

See the main skill's rule file for complete guidance:

• rules/surrealism.md -- project setup, Rust function signatures, WASM compilation, DEFINE MODULE/BUCKET syntax, deployment, testing, and best practices
• SurrealDB Extensions Docs -- official documentation
• CLI module command -- surreal module reference