Crate somnia 

somnia — Type-safe SurrealDB ORM

use somnia::{SomniaClient, SurrealRecord, Thing};
use serde::{Deserialize, Serialize};

#[derive(SurrealRecord, Serialize, Deserialize)]
#[table("asset")]
struct Asset {
    #[field(thing)]
    id: Thing<Asset>,
    name: String,
    #[field(name = "content_type")]
    content_type: Option<String>,
    file_size: Option<i64>,
}

async fn example() -> Result<(), SomniaError> {
    let db = SomniaClient::connect("ws://localhost:8000", "root", "root", "ns", "db").await?;

    // Typed column accessors are generated by the derive macro:
    let videos: Vec<Asset> = db.query(
        &Asset::table()
            .select(Asset::all())
            .filter(Asset::name().eq("video/mp4".to_string()))
            .filter(Asset::file_size().gt(1024 * 1024))
            .limit(10)
    ).await?;

    let db = db;
    Ok(())
}

Re-exports

pub use connection::SomniaClient;

pub use migrate::MigrationStatus;

pub use migrate::Migrator;

Modules

connection

migrate

Diesel-style migration runner for SurrealDB.

Structs

Batch

Concatenates SurrealQL statements with ; separators. The store’s typical pattern is a mutation followed by a SELECT that re-projects the row.

Column

ColumnMeta

ColumnSet

Select-all (*) column list. Generated by #[derive(SurrealRecord)].

Create

CREATE <target> [CONTENT … | SET …] [RETURN …].

Delete

Func

A SurrealQL function call name(args…).

Grouped

Wraps an expression in parentheses: (<expr>). Use to force grouping/precedence.

Ident

An untyped identifier (column or field path) for building filter expressions where a typed Column accessor is unavailable (e.g. record-link fields the derive doesn’t expose, or tenant.slug paths). Mirrors Column’s operators.

Insert

NoneLit

SurrealDB’s NONE.

Projection

A single SELECT-list entry. Either a bare expression or <expr> AS <alias>.

Raw

A verbatim SurrealQL fragment. Use for expressions somnia does not model as typed nodes (e.g. IF x != NONE THEN … END, lambdas, tenant.slug).

RecordLink

Builds a SurrealDB record link type::record('table', <key>). The key is any literal value (typically the bare UUID/string id of the related row).

Relate

RelateEdge

Build a RELATE query with edge content.

Select

Table

Thing

A typed SurrealDB record ID. Thing<Asset> → asset:xyz.

Update

Enums

Key

The key part of a SurrealDB record ID (the part after table:).

Order

Returning

How a mutating statement should return its affected rows.

SomniaError

Traits

DynExpr

SurrealEdge

Marker for edge records.

SurrealQL

SurrealRecord

SurrealSchema

Schema definition for a record type — lets the Rust type be the single source of truth for the SurrealDB schema. Implemented by #[derive(SurrealRecord)]; emits idempotent DDL and reversible up() / down() migrations.

Functions

col

A bare column name as a projection: name.

field

<raw> AS <alias> — verbatim expression with an alias.

ident

Construct an Ident for a field name.

Type Aliases

DynExprBox

A boxed, type-erased expression. Useful for returning a composed filter from a helper function (e.g. a shared tenant/owner predicate).

Derive Macros

SurrealRecord