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