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 INLINECODE4
Development Workflow
CODEBLOCK0
Quick Start
CODEBLOCK1
CODEBLOCK2
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:
Surrealism -- SurrealDB的WASM扩展
SurrealDB 3中的新特性。用Rust编写自定义函数，编译为WebAssembly（WASM），并将其部署为可从SurrealQL调用的原生数据库模块。
前置条件
- - Rust工具链（稳定版），带有wasm32-unknown-unknown目标
- SurrealDB CLI v3.0.0+（包含surreal module子命令的surreal二进制文件）
- 熟悉SurrealQL的DEFINE MODULE和DEFINE BUCKET
开发工作流
- 1. 注解 -- surrealism.toml + Rust函数上的#[surrealism]
- 编译 -- surreal module compile（生成.wasm二进制文件）
- 注册 -- 在SurrealQL中执行DEFINE BUCKET + DEFINE MODULE
快速开始
bash
创建一个新的Surrealism项目
cargo new --lib my_extension
cd my_extension
添加WASM目标
rustup target add wasm32-unknown-unknown
创建surrealism.toml（必需的清单文件）
cat > surrealism.toml << TOML
[package]
name = my_extension
version = 0.1.0
TOML
编写你的扩展（使用#[surrealism]注解）
cat > src/lib.rs << RUST
use surrealism::surrealism;
#[surrealism]
fn greet(name: String) -> String {
format!(Hello, {}!, name)
}
RUST
使用SurrealDB CLI编译为WASM
surreal module compile
在SurrealDB中注册
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test
surql
-- 授予对WASM文件的访问权限
DEFINE BUCKET my_bucket;
-- 注册模块函数
DEFINE MODULE myextension FROM mybucket:my_extension.wasm;
-- 在查询中使用函数
SELECT my_extension::greet(World);
使用场景
- - 可从SurrealQL调用的自定义标量函数
- 用于测试的伪造/模拟数据生成
- 领域特定逻辑（语言处理、量化金融、自定义编码）
- 访问对SurrealDB核心来说过于特定的小众Rust crate功能
- 全文搜索的自定义分析器
状态
Surrealism正在积极开发中，尚未稳定。API可能在SurrealDB 3.x版本之间发生变化。请通过GitHub issues/PR在surrealdb/surrealdb仓库提交反馈。
完整文档
有关完整指南，请参阅主要技能的规则文件：
