Struct Datastore

#[non_exhaustive]
pub struct Datastore { /* private fields */ }

The underlying datastore instance which stores the dataset.

Implementations

impl Datastore

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

Creates a new datastore instance

Examples

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

Or to create a file-backed store:

let ds = Datastore::new("surrealkv://temp.skv").await?;

Or to connect to a tikv-backed distributed store:

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

pub async fn new_with_clock( path: &str, clock: Option<Arc<SizedClock>>, ) -> Result<Datastore, Error>

pub fn restart(self) -> Self

Create a new datastore with the same persistent data (inner), with flushed cache. Simulating a server restart

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 with_temporary_directory(self, path: Option<PathBuf>) -> Self

Set a temporary directory for ordering of large result sets

pub fn index_store(&self) -> &IndexStores

pub fn is_auth_enabled(&self) -> bool

Is authentication enabled for this Datastore?

pub fn id(&self) -> Uuid

pub fn allows_http_route(&self, route_target: &RouteTarget) -> bool

Does the datastore allow requesting an HTTP route? This function needs to be public to allow access from the CLI crate.

pub fn get_capabilities(&self) -> &Capabilities

Set specific capabilities for this Datastore

pub fn get_cache(&self) -> Arc<DatastoreCache>

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

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

pub async fn initialise_credentials( &self, user: &str, pass: &str, ) -> Result<(), Error>

Setup the initial cluster access credentials

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

Initialise the cluster and run bootstrap utilities

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

Run the background task to update node registration information

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

Run the background task to process and archive inactive nodes

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

Run the background task to process and cleanup archived nodes

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

Run the background task to perform changefeed garbage collection

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

Run the background task to perform changefeed garbage collection

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

Run the datastore shutdown tasks, perfoming any necessary cleanup

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

Create a new transaction on this datastore

use surrealdb_core::kvs::{Datastore, TransactionType::*, LockType::*};
use surrealdb_core::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_core::kvs::Datastore;
use surrealdb_core::err::Error;
use surrealdb_core::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 execute_import<S>( &self, sess: &Session, vars: Option<BTreeMap<String, Value>>, query: S, ) -> Result<Vec<Response>, Error>

where S: Stream<Item = Result<Bytes, Error>>,

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_core::kvs::Datastore;
use surrealdb_core::err::Error;
use surrealdb_core::dbs::Session;
use surrealdb_core::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_core::kvs::Datastore;
use surrealdb_core::err::Error;
use surrealdb_core::dbs::Session;
use surrealdb_core::sql::Future;
use surrealdb_core::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 record access SIGNUP or SIGNIN clause, which still needs to work without guest access.

use surrealdb_core::kvs::Datastore;
use surrealdb_core::err::Error;
use surrealdb_core::dbs::Session;
use surrealdb_core::sql::Future;
use surrealdb_core::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_core::kvs::Datastore;
use surrealdb_core::err::Error;
use surrealdb_core::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 import( &self, sql: &str, sess: &Session, ) -> Result<Vec<Response>, Error>

Performs a database import from SQL

pub async fn import_stream<S>( &self, sess: &Session, stream: S, ) -> Result<Vec<Response>, Error>

where S: Stream<Item = Result<Bytes, Error>>,

Performs a database import from SQL

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

Performs a full database export as SQL

pub async fn export_with_config( &self, sess: &Session, chn: Sender<Vec<u8>>, cfg: Config, ) -> Result<impl Future<Output = Result<(), Error>>, Error>

Performs a full database export as SQL

pub fn check( &self, sess: &Session, action: Action, resource: Resource, ) -> Result<(), Error>

Checks the required permissions level for this session

pub fn setup_options(&self, sess: &Session) -> Options

pub fn setup_ctx(&self) -> Result<MutableContext, Error>

pub fn check_anon(&self, sess: &Session) -> Result<(), IamError>

check for disallowed anonymous users

impl Datastore

pub async fn insert_node(&self, id: Uuid) -> Result<(), Error>

Inserts a node for the first time into the cluster.

This function should be run at server or database startup.

This function ensures that this node is entered into the clister membership entries. This function must be run at server or database startup, in order to write the initial entry and timestamp to storage.

pub async fn update_node(&self, id: Uuid) -> Result<(), Error>

Updates an already existing node in the cluster.

This function should be run periodically at a regular interval.

This function updates the entry for this node with an up-to-date timestamp. This ensures that the node is not marked as expired by any garbage collection tasks, preventing any data cleanup for this node.

pub async fn delete_node(&self, id: Uuid) -> Result<(), Error>

Deletes a node from the cluster.

This function should be run when a node is shutting down.

This function marks the node as archived, ready for garbage collection. Later on when garbage collection is running the live queries assigned to this node will be removed, along with the node itself.

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

Expires nodes which have timedout from the cluster.

This function should be run periodically at an interval.

This function marks the node as archived, ready for garbage collection. Later on when garbage collection is running the live queries assigned to this node will be removed, along with the node itself.

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

Removes and cleans up nodes which are no longer in this cluster.

This function should be run periodically at an interval.

This function clears up all nodes which have been marked as archived. When a matching node is found, all node queries, and table queries are garbage collected, before the node itself is completely deleted.

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

Clean up all other miscellaneous data.

This function should be run periodically at an interval.

This function clears up all data which might have been missed from previous cleanup runs, or when previous runs failed. This function currently deletes all live queries, for nodes which no longer exist in the cluster, from all namespaces, databases, and tables. It uses a number of transactions in order to prevent failure of large or long-running transactions on distributed storage engines.

pub async fn delete_queries(&self, ids: Vec<Uuid>) -> Result<(), Error>

Clean up the live queries for a disconnected connection.

This function should be run when a WebSocket disconnects.

This function clears up the live queries on the current node, which are specified by uique live query UUIDs. This is necessary when a WebSocket disconnects, and any associated live queries need to be cleaned up and removed.

Trait Implementations

impl Display for Datastore

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

Formats the value using the given formatter.