Struct Database 

pub struct Database {
    pub(crate) inner: NonNull<FDB_database>,
}

Re-export the foundationdb crate for convenience. Represents a FoundationDB database

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

Modifications to a database are performed via transactions.

Fields

inner: NonNull<FDB_database>

Implementations

impl Database

pub fn new(path: Option<&str>) -> Result<Database, FdbError>

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

pub unsafe fn new_from_pointer(ptr: NonNull<FDB_database>) -> Database

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

Safety

The caller must ensure that ptr is a valid pointer to an FDBDatabase object obtained from the FoundationDB C API, and that the pointer is not aliased or used after being passed to this function.

pub fn from_path(path: &str) -> Result<Database, FdbError>

Create a database for the given configuration path

pub fn default() -> Result<Database, FdbError>

Create a database for the default configuration path

impl Database

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

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

impl Database

pub async fn new_compat(path: Option<&str>) -> Result<Database, FdbError>

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.

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

Called to set an option an on Database.

pub fn create_trx(&self) -> Result<Transaction, FdbError>

Creates a new transaction on the given database.

pub fn create_instrumented_trx( &self, metrics: TransactionMetrics, ) -> Result<Transaction, FdbBindingError>

Creates a new transaction on the given database with metrics collection.

This method is similar to create_trx() but additionally collects metrics about the transaction execution, including operation counts, bytes read/written, and retry counts.

Arguments

• metrics - A TransactionMetrics instance to collect metrics

Returns

• Result<Transaction, (FdbBindingError, MetricsData)> - A transaction with metrics collection enabled

pub fn create_intrumented_retryable_trx( &self, metrics: TransactionMetrics, ) -> Result<RetryableTransaction, FdbBindingError>

Creates a new retryable transaction on the given database with metrics collection.

This method is similar to create_retryable_trx() but additionally collects metrics about the transaction execution, including operation counts, bytes read/written, and retry counts.

Arguments

• metrics - A TransactionMetrics instance to collect metrics

Returns

• Result<RetryableTransaction, (FdbBindingError, MetricsData)> - A retryable transaction with metrics collection enabled

pub async fn transact<F>( &self, f: F, options: TransactOption, ) -> Result<<F as DatabaseTransact>::Item, <F as DatabaseTransact>::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.

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 F: for<'a> 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,

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 F: for<'a> FnMut(&'a Transaction, &'a mut D) -> Pin<Box<dyn Future<Output = Result<T, E>> + 'a>> + 'trx, E: TransactError + 'trx, T: 'trx, D: 'trx,

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 needs 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 be used as boolean with

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

pub async fn instrumented_run<F, Fut, T>( &self, closure: F, ) -> Result<(T, MetricsReport), (FdbBindingError, MetricsReport)>

where F: Fn(RetryableTransaction, MaybeCommitted) -> Fut, Fut: Future<Output = Result<T, FdbBindingError>>,

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

This method is similar to run() but additionally collects and returns metrics about the transaction execution, including operation counts, bytes read/written, and retry counts.

Arguments

• closure - A function that takes a RetryableTransaction and MaybeCommitted flag and returns a Future

Returns

• Result<(T, Metrics), (FdbBindingError, Metrics)> - On success, returns the result of the transaction and collected metrics. On failure, returns the error and the metrics collected up to the point of failure.

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 needs to be guaranteed to finish.

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. The closure will be notified of a maybe_committed transaction in a previous run with the MaybeCommitted provided in the closure.

pub async fn perform_no_op(&self) -> Result<(), FdbError>

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.

pub async fn get_main_thread_busyness(&self) -> Result<f64, FdbError>

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.

Trait Implementations

impl Drop for Database

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Database

impl Sync for Database