Crate foundationdb

FoundationDB Rust Client API

This is a wrapper library around the FoundationDB (Fdb) C API. It implements futures based interfaces over the Fdb future C implementations.

Prerequisites

Install FoundationDB

Install FoundationDB on your system, see FoundationDB Local Development, or these instructions:

• Ubuntu Linux (this may work on the Linux subsystem for Windows as well)

$> curl -O https://www.foundationdb.org/downloads/6.2.25/ubuntu/installers/foundationdb-clients_6.2.25-1_amd64.deb
$> curl -O https://www.foundationdb.org/downloads/6.2.25/ubuntu/installers/foundationdb-server_6.2.25-1_amd64.deb
$> sudo dpkg -i foundationdb-clients_6.2.25-1_amd64.deb
$> sudo dpkg -i foundationdb-server_6.2.25-1_amd64.deb

• macOS

$> curl -O https://www.foundationdb.org/downloads/6.2.25/macOS/installers/FoundationDB-6.2.25.pkg
$> sudo installer -pkg FoundationDB-6.2.25.pkg -target /

• Windows

Install foundationdb-6.2.25-x64.msi

Add dependencies on foundationdb-rs

[dependencies]
foundationdb = "0.5"
futures = "0.3"

Initialization

Due to limitations in the C API, the Client and it's associated Network can only be initialized and run once per the life of a process. Generally the foundationdb::init function will be enough to initialize the Client. See foundationdb::default_api and foundationdb::builder for more configuration options of the Fdb Client.

Example

use futures::prelude::*;

async fn async_main() -> foundationdb::FdbResult<()> {
    let db = foundationdb::Database::default()?;

    // write a value
    let trx = db.create_trx()?;
    trx.set(b"hello", b"world"); // errors will be returned in the future result
    trx.commit().await?;

    // read a value
    let trx = db.create_trx()?;
    let maybe_value = trx.get(b"hello", false).await?;
    let value = maybe_value.unwrap(); // unwrap the option

    assert_eq!(b"world", &value.as_ref());

    Ok(())
}

// Safe because drop is called before the program exits
let network = unsafe { foundationdb::boot() };
futures::executor::block_on(async_main()).expect("failed to run");
drop(network);

#[tokio::main]
async fn main() {
    // Safe because drop is called before the program exits
    let network = unsafe { foundationdb::boot() };

    // Have fun with the FDB API

    // shutdown the client
    drop(network);
}

API stability

WARNING Until the 1.0 release of this library, the API may be in constant flux.

Modules

api	Configuration of foundationDB API and Network
future	Most functions in the FoundationDB API are asynchronous, meaning that they may return to the caller before actually delivering their Fdbresult.
options	Generated configuration types for use with the various set_option functions
tuple	Implementation of the official tuple layer typecodes

Structs

Database	Represents a FoundationDB database
FdbError	The Standard Error type of FoundationDB
KeySelector	A KeySelector identifies a particular key in the database.
RangeOption	RangeOption represents a query parameters for range scan query.
TransactOption	A set of options that controls the behavior of Database::transact.
Transaction	In FoundationDB, a transaction is a mutable snapshot of a database.
TransactionCancelled	A cancelled transaction
TransactionCommitError	A failed to commit transaction.
TransactionCommitted	A committed transaction.

Traits

DatabaseTransact
TransactError	A trait that must be implemented to use Database::transact this application error types.

Functions

boot⚠	Initialize the FoundationDB Client API, this can only be called once per process.
default_config_path	Returns the default Fdb cluster configuration file path

Type Definitions

FdbResult

Alias for Result<..., FdbError>