[−][src]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 |
tuple | Implementation of the official tuple layer typecodes |
Structs
Database | Represents a FoundationDB database |
FdbError | The Standard Error type of FoundationDB |
KeySelector | A |
RangeOption |
|
TransactOption | A set of options that controls the behavior of |
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 |
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 |