[][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/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

cluster

Implementations of the FDBCluster C API

database

Implementations of the FDBDatabase C API

error

Error types for the Fdb crate

fdb_api

Implementations of the Fdb API versioning C API

future

Most functions in the FoundationDB API are asynchronous, meaning that they may return to the caller before actually delivering their result.

keyselector

A KeySelector identifies a particular key in the database.

network

Implementations of the Network related functions for FoundationDB

options

Generated configuration types for use with the various set_option functions

transaction

Implementations of the FDBTransaction C API

tuple

Tuple Key type like that of other FoundationDB libraries

Structs

Subspace

Represents a well-defined region of keyspace in a FoundationDB database

Functions

builder

Allows the API version, etc, to be configured before starting.

default_api

Initialize the FoundationDB Client API, this can only be called once per process.

default_config_path

Returns the default Fdb cluster configuration file path

init

Initialize the FoundationDB Client API, this can only be called once per process.