oneiriq-surql 0.2.2

Code-first database toolkit for SurrealDB - schema definitions, migrations, query building, and typed CRUD (Rust port of oneiriq-surql). Published as the `oneiriq-surql` crate; imported as `use surql::...`.
Documentation

surql-rs

License Rust SurrealDB

A code-first database toolkit for SurrealDB. Define schemas, generate migrations, build queries, and perform typed CRUD -- all from Rust.

Features

  • Code-First Migrations - Schema changes defined in code with automatic migration generation (auto-diff, .surql file output with -- @up / -- @down sections, squash, hooks).
  • Type-Safe Query Builder - Immutable fluent API with operator-typed where_, expression helpers, serde integration, and first-class Query::execute / Query::select_expr.
  • Query UX Helpers - type_record / type_thing, extract_many / has_result, aggregate_records + AggregateOpts hoisted to the crate root.
  • Async-First - Tokio-based client on surrealdb 3.x with connection pooling, retry logic, and buffered transactions.
  • Vector Search - HNSW and MTREE index support with 8 distance metrics and EFC/M tuning.
  • Graph Traversal - Native SurrealDB graph features with edge relationships (v3-compatible arrow chains).
  • Schema Visualization - Mermaid, GraphViz, and ASCII diagrams with theming.
  • CLI Tools - Full surql binary (migrate, schema, db, orchestrate) behind the cli feature.
  • Optional subsystems - cache (memory + Redis), settings, orchestration, watcher feature flags.

Quick Start

cargo add oneiriq-surql

Pure-Rust TLS (no openssl-sys, recommended for CI runners without libssl-dev):

cargo add oneiriq-surql --no-default-features --features client-rustls

With the CLI:

cargo install oneiriq-surql --features cli

TLS backends

  • client (default) -- async client backed by native-tls; links openssl-sys on Linux, Security.framework on macOS.
  • client-rustls -- same client surface, pure-Rust TLS via rustls

Define a schema

use surql::schema::table::{table_schema, TableMode, unique_index};
use surql::schema::fields::{string_field, int_field, datetime_field};

let user_schema = table_schema("user")
    .mode(TableMode::Schemafull)
    .field(string_field("name"))
    .field(string_field("email").assertion("string::is::email($value)"))
    .field(int_field("age").assertion("$value >= 0 AND $value <= 150"))
    .field(datetime_field("created_at").default("time::now()").readonly(true))
    .index(unique_index("email_idx", &["email"]))
    .build()?;

Execute a typed query

use surql::{DatabaseClient, type_record, extract_many};
use surql::connection::ConnectionConfig;
use surql::query::builder::Query;
use surql::query::expressions::{as_, count_all, math_mean};
use surql::types::operators::eq;

let client = DatabaseClient::new(ConnectionConfig::default())?;
client.connect().await?;

// First-class target: `type::record('user', 'alice')`.
let target = type_record("user", "alice").to_surql();

// Typed select projection + `.execute(&client)` on the builder.
let raw = Query::new()
    .select_expr(vec![
        as_(&count_all(), "total"),
        as_(&math_mean("score"), "mean_score"),
    ])
    .from_table("memory_entry")?
    .where_(&eq("status", "active"))
    .group_all()
    .execute(&client)
    .await?;

for row in extract_many(&raw) {
    println!("{row}");
}

Aggregate with AggregateOpts

use surql::query::{aggregate_records, AggregateOpts};
use surql::query::expressions::{count_all, math_mean};
use surql::types::operators::eq;

let rows = aggregate_records(
    &client,
    "memory_entry",
    AggregateOpts {
        select: vec![
            ("total".into(), count_all()),
            ("mean_score".into(), math_mean("score")),
        ],
        where_: Some(eq("status", "active")),
        group_all: true,
        ..AggregateOpts::default()
    },
)
.await?;

Documentation

Full documentation at oneiriq.github.io/surql-rs.

Selected pages:

Requirements

  • Rust 1.90+
  • SurrealDB 3.0+

License

Apache License 2.0 - see LICENSE.

Python / TypeScript / Go

  • Python: surql-py -- the original, reference implementation (Python 3.12+).
  • TypeScript / Deno / Node.js: surql -- type-safe query builder and client.
  • Go: surql-go -- Go port of this library, sharing the same schema + migration model.

Support