Crate surrealdb

This library provides a low-level database library implementation, a remote client and a query language definition, for SurrealDB, the ultimate cloud database for tomorrow’s applications. SurrealDB is a scalable, distributed, collaborative, document-graph database for the realtime web.

This library can be used to start an embedded in-memory datastore, an embedded datastore persisted to disk, a browser-based embedded datastore backed by IndexedDB, or for connecting to a distributed TiKV key-value store.

It also enables simple and advanced querying of a remote SurrealDB server from server-side or client-side code. All connections to SurrealDB are made over WebSockets by default, and automatically reconnect when the connection is terminated.

Examples

use std::borrow::Cow;
use serde::{Serialize, Deserialize};
use serde_json::json;
use surrealdb::{Error, Surreal};
use surrealdb::opt::auth::Root;
use surrealdb::engine::remote::ws::Ws;

#[derive(Serialize, Deserialize)]
struct Person {
    title: String,
    name: Name,
    marketing: bool,
}

// Pro tip: Replace String with Cow<'static, str> to
// avoid unnecessary heap allocations when inserting

#[derive(Serialize, Deserialize)]
struct Name {
    first: Cow<'static, str>,
    last: Cow<'static, str>,
}

// Install at https://surrealdb.com/install
// and use `surreal start --user root --pass root`
// to start a working database to take the following queries
// See the results via `surreal sql --ns namespace --db database --pretty`
// or https://surrealist.app/
// followed by the query `SELECT * FROM person;`
#[tokio::main]
async fn main() -> Result<(), Error> {
    let db = Surreal::new::<Ws>("localhost:8000").await?;

    // Signin as a namespace, database, or root user
    db.signin(Root {
        username: "root",
        password: "root",
    }).await?;

    // Select a specific namespace / database
    db.use_ns("namespace").use_db("database").await?;

    // Create a new person with a random ID
    let created: Vec<Person> = db.create("person")
        .content(Person {
            title: "Founder & CEO".into(),
            name: Name {
                first: "Tobie".into(),
                last: "Morgan Hitchcock".into(),
            },
            marketing: true,
        })
        .await?;

    // Create a new person with a specific ID
    let created: Option<Person> = db.create(("person", "jaime"))
        .content(Person {
            title: "Founder & COO".into(),
            name: Name {
                first: "Jaime".into(),
                last: "Morgan Hitchcock".into(),
            },
            marketing: false,
        })
        .await?;

    // Update a person record with a specific ID
    let updated: Option<Person> = db.update(("person", "jaime"))
        .merge(json!({"marketing": true}))
        .await?;

    // Select all people records
    let people: Vec<Person> = db.select("person").await?;

    // Perform a custom advanced query
    let query = r#"
        SELECT marketing, count()
        FROM type::table($table)
        GROUP BY marketing
    "#;

    let groups = db.query(query)
        .bind(("table", "person"))
        .await?;

    Ok(())
}

Modules

engine

Different embedded and remote database engines

error

Different error types for embedded and remote databases

method

Methods to use when interacting with a SurrealDB instance

opt

The different options and types for use in API functions

sql

The full type definitions for the SurrealQL query language

Macros

enter_flexible_ident

enter_object_recursion

enter_query_recursion

lazy_env_parse

A macro that allows lazily parsing a value from the environment variable, with a fallback default value if the variable is not set or parsing fails.

lazy_env_parse_or_else

Lazily parses an environment variable into a specified type. If the environment variable is not set or the parsing fails, it returns a default value.

Structs

Connect

The future returned when creating a new SurrealDB instance

Notification

A live query notification

Response

The response type of a Surreal::query request

Surreal

A database client instance for embedded or remote databases

Enums

Action

The action performed on a record

Error

An error originating from the SurrealDB client library

Traits

Connection

Connection trait implemented by supported engines

Type Aliases

Result

A specialized Result type