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 serde::{Serialize, Deserialize};
use serde_json::json;
use std::borrow::Cow;
use surrealdb::{Result, Surreal};
use surrealdb::sql;
use surrealdb::opt::auth::Root;
use surrealdb::engine::remote::ws::Ws;

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

#[derive(Serialize, Deserialize)]
struct Person {
    title: Cow<'static, str>,
    name: Name,
    marketing: bool,
}

#[tokio::main]
async fn main() -> Result<()> {
    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 sql = r#"
        SELECT marketing, count()
        FROM type::table($table)
        GROUP BY marketing
    "#;

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

    Ok(())
}

Modules

cnf

dbs

Datastore module which is the core of the database node. In this module we essentially manage the entire lifecycle of a database request acting as the glue between the API and the response. In this module we use channels as a transport layer and executors to process the operations. This module also gives a context to the transaction.

engine

Different embedded and remote database engines

env

err

error

Different error types for embedded and remote databases

iam

idg

idx

key

How the keys are structured in the key value store

kvs

The module defining the key value store. Everything related the transaction for the key value store is defined in the tx.rs file. This module enables the following operations on the key value store:

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

syn

Module containing the implementation of the surrealql tokens, lexer, and parser.

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