Struct Database

Source

pub struct Database { /* private fields */ }

Expand description

Represents a FoundationDB database

A mutable, lexicographically ordered mapping from binary keys to binary values.

Modifications to a database are performed via transactions.

Implementations§

Source §

impl Database

Source

pub fn new(path: Option<&str>) -> FdbResult<Database>

Create a database for the given configuration path if any, or the default one.

Source

pub fn new_from_pointer(ptr: NonNull<FDBDatabase>) -> Self

Create a new FDBDatabase from a raw pointer. Users are expected to use the new method.

Source

pub fn from_path(path: &str) -> FdbResult<Database>

Create a database for the given configuration path

Source

pub fn default() -> FdbResult<Database>

Create a database for the default configuration path

Source §

impl Database

Source

pub fn get_client_status( &self, ) -> impl Future<Output = FdbResult<FdbSlice>> + Send + Sync + Unpin

Retrieve a client-side status information in a JSON format.

Source §

impl Database

Source

pub async fn new_compat(path: Option<&str>) -> FdbResult<Database>

Create a database for the given configuration path

This is a compatibility api. If you only use API version ≥ 610 you should use Database::new, Database::from_path or Database::default.

Source

pub fn set_option(&self, opt: DatabaseOption) -> FdbResult<()>

Called to set an option an on Database.

Source

pub fn create_trx(&self) -> FdbResult<Transaction>

Creates a new transaction on the given database.

Source

pub async fn transact<F>( &self, f: F, options: TransactOption, ) -> Result<F::Item, F::Error>
where F: DatabaseTransact,

transact returns a future which retries on error. It tries to resolve a future created by caller-provided function f inside a retry loop, providing it with a newly created transaction. After caller-provided future resolves, the transaction will be committed automatically.

§Warning

It might retry indefinitely if the transaction is highly contentious. It is recommended to set TransactionOption::RetryLimit or TransactionOption::SetTimeout on the transaction if the task need to be guaranteed to finish.

Once Generic Associated Types lands in stable rust, the returned future of f won’t need to be boxed anymore, also the lifetime limitations around f might be lowered.

Source

pub fn transact_boxed<'trx, F, D, T, E>( &'trx self, data: D, f: F, options: TransactOption, ) -> impl Future<Output = Result<T, E>> + Send + 'trx
where for<'a> F: FnMut(&'a Transaction, &'a mut D) -> Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'a>> + Send + 'trx, E: TransactError + Send + 'trx, T: Send + 'trx, D: Send + 'trx,

Source

pub fn transact_boxed_local<'trx, F, D, T, E>( &'trx self, data: D, f: F, options: TransactOption, ) -> impl Future<Output = Result<T, E>> + 'trx
where for<'a> F: FnMut(&'a Transaction, &'a mut D) -> Pin<Box<dyn Future<Output = Result<T, E>> + 'a>> + 'trx, E: TransactError + 'trx, T: 'trx, D: 'trx,

Source

pub async fn run<F, Fut, T>(&self, closure: F) -> Result<T, FdbBindingError>
where F: Fn(RetryableTransaction, MaybeCommitted) -> Fut, Fut: Future<Output = Result<T, FdbBindingError>>,

Runs a transactional function against this Database with retry logic. The associated closure will be called until a non-retryable FDBError is thrown or commit(), returns success.

Users are not expected to keep reference to the RetryableTransaction. If a weak or strong reference is kept by the user, the binding will throw an error.

§Warning: retry

It might retry indefinitely if the transaction is highly contentious. It is recommended to set options::TransactionOption::RetryLimit or options::TransactionOption::Timeout on the transaction if the task need to be guaranteed to finish. These options can be safely set on every iteration of the closure.

§Warning: Maybe committed transactions

As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. You should make sure your closure is idempotent.

The closure will notify the user in case of a maybe_committed transaction in a previous run with the MaybeCommitted provided in the closure.

This one can used as boolean with

db.run(|trx, maybe_committed| async {
    if maybe_committed.into() {
        // Handle the problem if needed
    }
}).await;

Source

pub async fn perform_no_op(&self) -> FdbResult<()>

Perform a no-op against FDB to check network thread liveness. This operation will not change the underlying data in any way, nor will it perform any I/O against the FDB cluster. However, it will schedule some amount of work onto the FDB client and wait for it to complete. The FoundationDB client operates by scheduling onto an event queue that is then processed by a single thread (the “network thread”). This method can be used to determine if the network thread has entered a state where it is no longer processing requests or if its time to process requests has increased. If the network thread is busy, this operation may take some amount of time to complete, which is why this operation returns a future.

Source

pub async fn get_main_thread_busyness(&self) -> FdbResult<f64>

Returns a value where 0 indicates that the client is idle and 1 (or larger) indicates that the client is saturated. By default, this value is updated every second.