Struct Datastore

pub struct Datastore { /* private fields */ }

The underlying datastore instance which stores the dataset.

Implementations

impl Datastore

pub async fn new(path: &str) -> Result<Datastore, Error>

Creates a new datastore instance

Examples

let ds = Datastore::new("memory").await?;

Or to create a file-backed store:

let ds = Datastore::new("file://temp.db").await?;

Or to connect to a tikv-backed distributed store:

let ds = Datastore::new("tikv://127.0.0.1:2379").await?;

pub fn with_node_id(self, id: Uuid) -> Self

Specify whether this Datastore should run in strict mode

pub fn with_strict_mode(self, strict: bool) -> Self

Specify whether this Datastore should run in strict mode

pub fn with_notifications(self) -> Self

Specify whether this datastore should enable live query notifications

pub fn with_query_timeout(self, duration: Option<Duration>) -> Self

Set a global query timeout for this Datastore

pub fn with_transaction_timeout(self, duration: Option<Duration>) -> Self

Set a global transaction timeout for this Datastore

pub fn with_auth_enabled(self, enabled: bool) -> Self

Set whether authentication is enabled for this Datastore

pub fn with_capabilities(self, caps: Capabilities) -> Self

Set specific capabilities for this Datastore

pub fn is_auth_enabled(&self) -> bool

Is authentication enabled for this Datastore?

pub async fn setup_initial_creds(&self, creds: Root<'_>) -> Result<(), Error>

Setup the initial credentials Trigger the unreachable definition compilation error, probably due to this issue: https://github.com/rust-lang/rust/issues/111370

pub async fn bootstrap(&self) -> Result<(), Error>

pub async fn register_remove_and_archive( &self, tx: &mut Transaction, node_id: &Uuid, ) -> Result<Vec<(LqValue, Option<Error>)>, Error>

pub async fn register_membership( &self, tx: &mut Transaction, node_id: &Uuid, timestamp: Timestamp, ) -> Result<(), Error>

pub async fn remove_dead_nodes( &self, tx: &mut Transaction, ts: &Timestamp, ) -> Result<Vec<Uuid>, Error>

Delete dead heartbeats and nodes Returns node IDs

pub async fn archive_dead_lqs( &self, tx: &mut Transaction, nodes: &[Uuid], this_node_id: &Uuid, ) -> Result<Vec<(LqValue, Option<Error>)>, Error>

Accepts cluster IDs Archives related live queries Returns live query keys that can be used for deletes

The reason we archive first is to stop other nodes from picking it up for further updates This means it will be easier to wipe the range in a subsequent transaction

pub async fn remove_archived( &self, tx: &mut Transaction, archived: Vec<LqValue>, ) -> Result<(), Error>

pub async fn clear_unreachable_state( &self, tx: &mut Transaction, ) -> Result<(), Error>

pub async fn garbage_collect_dead_session( &self, live_queries: &[Uuid], ) -> Result<(), Error>

pub async fn archive_lv_for_node( &self, tx: &mut Transaction, nd: &Uuid, this_node_id: Uuid, ) -> Result<Vec<(LqValue, Option<Error>)>, Error>

pub async fn delete_dead_heartbeats( &self, tx: &mut Transaction, ts: &Timestamp, ) -> Result<Vec<Hb>, Error>

Given a timestamp, delete all the heartbeats that have expired Return the removed heartbeats as they will contain node information

pub async fn tick(&self) -> Result<(), Error>

pub async fn tick_at(&self, ts: u64) -> Result<(), Error>

pub async fn save_timestamp_for_versionstamp( &self, ts: u64, ) -> Result<(), Error>

pub async fn garbage_collect_stale_change_feeds( &self, ts: u64, ) -> Result<(), Error>

pub async fn heartbeat(&self) -> Result<(), Error>

pub async fn heartbeat_full( &self, tx: &mut Transaction, timestamp: Timestamp, node_id: Uuid, ) -> Result<(), Error>

pub async fn transaction( &self, write: TransactionType, lock: LockType, ) -> Result<Transaction, Error>

Create a new transaction on this datastore

use surrealdb::kvs::{Datastore, TransactionType::*, LockType::*};
use surrealdb::err::Error;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let ds = Datastore::new("file://database.db").await?;
    let mut tx = ds.transaction(Write, Optimistic).await?;
    tx.cancel().await?;
    Ok(())
}

pub async fn execute( &self, txt: &str, sess: &Session, vars: Option<BTreeMap<String, Value>>, ) -> Result<Vec<Response>, Error>

Parse and execute an SQL query

use surrealdb::kvs::Datastore;
use surrealdb::err::Error;
use surrealdb::dbs::Session;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let ds = Datastore::new("memory").await?;
    let ses = Session::owner();
    let ast = "USE NS test DB test; SELECT * FROM person;";
    let res = ds.execute(ast, &ses, None).await?;
    Ok(())
}

pub async fn process( &self, ast: Query, sess: &Session, vars: Option<BTreeMap<String, Value>>, ) -> Result<Vec<Response>, Error>

Execute a pre-parsed SQL query

use surrealdb::kvs::Datastore;
use surrealdb::err::Error;
use surrealdb::dbs::Session;
use surrealdb::sql::parse;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let ds = Datastore::new("memory").await?;
    let ses = Session::owner();
    let ast = parse("USE NS test DB test; SELECT * FROM person;")?;
    let res = ds.process(ast, &ses, None).await?;
    Ok(())
}

pub async fn compute( &self, val: Value, sess: &Session, vars: Option<BTreeMap<String, Value>>, ) -> Result<Value, Error>

Ensure a SQL Value is fully computed

use surrealdb::kvs::Datastore;
use surrealdb::err::Error;
use surrealdb::dbs::Session;
use surrealdb::sql::Future;
use surrealdb::sql::Value;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let ds = Datastore::new("memory").await?;
    let ses = Session::owner();
    let val = Value::Future(Box::new(Future::from(Value::Bool(true))));
    let res = ds.compute(val, &ses, None).await?;
    Ok(())
}

pub async fn evaluate( &self, val: Value, sess: &Session, vars: Option<BTreeMap<String, Value>>, ) -> Result<Value, Error>

Evaluates a SQL Value without checking authenticating config This is used in very specific cases, where we do not need to check whether authentication is enabled, or guest access is disabled. For example, this is used when processing a SCOPE SIGNUP or SCOPE SIGNIN clause, which still needs to work without guest access.

use surrealdb::kvs::Datastore;
use surrealdb::err::Error;
use surrealdb::dbs::Session;
use surrealdb::sql::Future;
use surrealdb::sql::Value;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let ds = Datastore::new("memory").await?;
    let ses = Session::owner();
    let val = Value::Future(Box::new(Future::from(Value::Bool(true))));
    let res = ds.evaluate(val, &ses, None).await?;
    Ok(())
}

pub fn notifications(&self) -> Option<Receiver<Notification>>

Subscribe to live notifications

use surrealdb::kvs::Datastore;
use surrealdb::err::Error;
use surrealdb::dbs::Session;

#[tokio::main]
async fn main() -> Result<(), Error> {
    let ds = Datastore::new("memory").await?.with_notifications();
    let ses = Session::owner();
	if let Some(channel) = ds.notifications() {
    	while let Ok(v) = channel.recv().await {
    	    println!("Received notification: {v}");
    	}
	}
    Ok(())
}

pub async fn export( &self, sess: &Session, ns: String, db: String, chn: Sender<Vec<u8>>, ) -> Result<impl Future<Output = Result<(), Error>>, Error>

Performs a full database export as SQL

pub async fn import( &self, sql: &str, sess: &Session, ) -> Result<Vec<Response>, Error>

Performs a database import from SQL

Trait Implementations

impl Display for Datastore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.