Crate foundationdb
source ·Expand description
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/5.1.5/ubuntu/installers/foundationdb-clients_5.1.5-1_amd64.deb
$> curl -O https://www.foundationdb.org/downloads/5.1.5/ubuntu/installers/foundationdb-server_5.1.5-1_amd64.deb
$> sudo dpkg -i foundationdb-clients_5.1.5-1_amd64.deb
$> sudo dpkg -i foundationdb-server_5.1.5-1_amd64.deb
- macOS
$> curl -O https://www.foundationdb.org/downloads/5.1.5/macOS/installers/FoundationDB-5.1.5.pkg
$> sudo installer -pkg FoundationDB-5.1.5.pkg -target /
Add dependencies on foundationdb-rs
[dependencies]
foundationdb = "*"
futures = "0.1"
Extern the crate in bin.rs
or lib.rs
extern crate foundationdb;
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
extern crate futures;
extern crate foundationdb;
use std::thread;
use futures::future::*;
use foundationdb::{self, *};
let network = foundationdb::init().expect("failed to initialize Fdb client");
let handle = std::thread::spawn(move || {
let error = network.run();
if let Err(error) = error {
panic!("fdb_run_network: {}", error);
}
});
// wait for the network thread to be started
network.wait();
// work with Fdb
let db = Cluster::new(foundationdb::default_config_path())
.and_then(|cluster| cluster.create_database())
.wait().expect("failed to create Cluster");
// set a value
let trx = db.create_trx().expect("failed to create transaction");
trx.set(b"hello", b"world"); // errors will be returned in the future result
trx.commit()
.wait()
.expect("failed to set hello to world");
// read a value
let trx = db.create_trx().expect("failed to create transaction");
let result = trx.get(b"hello", false).wait().expect("failed to read world from hello");
let value: &[u8] = result.value()
.unwrap(); // unwrap the option
// should print "hello world"
println!("hello {}", String::from_utf8_lossy(value));
// cleanly shutdown the client
network.stop().expect("failed to stop Fdb client");
handle.join();
API stability
WARNING Until the 1.0 release of this library, the API may be in constant flux.
Re-exports
pub use cluster::Cluster;
pub use database::Database;
pub use error::Error;
pub use transaction::Transaction;
Modules
Implementations of the FDBCluster C API
Implementations of the FDBDatabase C API
Error types for the Fdb crate
Implementations of the Fdb API versioning C API
Most functions in the FoundationDB API are asynchronous, meaning that they may return to the caller before actually delivering their result.
A
KeySelector
identifies a particular key in the database.Implementations of the Network related functions for FoundationDB
Generated configuration types for use with the various
set_option
functionsImplementations of the FDBTransaction C API
Tuple Key type like that of other FoundationDB libraries
Structs
Represents a well-defined region of keyspace in a FoundationDB database
Functions
Allows the API version, etc, to be configured before starting.
Initialize the FoundationDB Client API, this can only be called once per process.
Returns the default Fdb cluster configuration file path
Initialize the FoundationDB Client API, this can only be called once per process.