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

  • Rust 1.70.0 or more,
  • FoundationDB’s client installed.

§Platform Support

Support for different platforms (“targets”) are organized into three tiers, each with a different set of guarantees. For more information on the policies for targets at each tier, see the Target Tier Policy.

For more information on the policies for targets at each tier, see the

§Target Tier Policy

§Tier 1

Tier 1 targets can be thought of as “guaranteed to work”. This means that:

  • we are actively checking correctness with the BindingTester,
  • we are running classic Rust tests on each pull requests,
  • you can use the crate on the platform.

§Tier 2

Tier 2 targets can be thought of as “guaranteed to build”. This means that:

  • we are running classic Rust tests on each pull requests,
  • you can use the crate on the platform.

But we are not checking correctness.

§Tier 3

Tier 3 targets are platforms we would like to have as Tier 2. You might be able to compile, but no CI has been set up.

§Getting Started

§Install FoundationDB

You first need to install FoundationDB. You can follow the official documentation:

§Add dependencies on foundationdb-rs

cargo add foundationdb -F embedded-fdb-include
cargo add futures

This Rust crate is not tied to any Async Runtime.

§Exposed features

FeaturesNotes
fdb-5_1Support for FoundationDB 5.1.X
fdb-5_2Support for FoundationDB 5.2.X
fdb-6_0Support for FoundationDB 6.0.X
fdb-6_1Support for FoundationDB 6.1.X
fdb-6_2Support for FoundationDB 6.2.X
fdb-6_3Support for FoundationDB 6.3.X
fdb-7_0Support for FoundationDB 7.0.X
fdb-7_1Support for FoundationDB 7.1.X
embedded-fdb-includeUse the locally embedded FoundationDB fdb_c.h and fdb.options files to compile
uuidSupport for the uuid crate for Tuples
num-bigintSupport for the bigint crate for Tuples
tenant-experimentalExperimental support for tenants. Require at least 7.1

§Hello, World using the crate

We are going to use the Tokio runtime for this example:

use futures::prelude::*;

#[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
    hello_world().await.expect("could not run the hello world");

    // shutdown the client
    drop(network);
}

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

    // write a value in a retryable closure
    match db
        .run(|trx, _maybe_committed| async move {
            trx.set(b"hello", b"world");
            Ok(())
        })
        .await
    {
        Ok(_) => println!("transaction committed"),
        Err(_) => eprintln!("cannot commit transaction"),
    };

    // read a value
    match db
        .run(|trx, _maybe_committed| async move { Ok(trx.get(b"hello", false).await.unwrap()) })
        .await
    {
        Ok(slice) => assert_eq!(b"world", slice.unwrap().as_ref()),
        Err(_) => eprintln!("cannot commit transaction"),
    }

    Ok(())
}

§Additional notes

§The class-scheduling tutorial

The official FoundationDB’s tutorial is called the Class Scheduling. You can find the Rust version in the examples.

§The blob tutorial

The official FoundationDB documentation provides also another topic which is further discussed inside a design recipe. A Rust implementation can be found here.

Another example, explores how to use subspaces to attach metadata to our blob.

§Must-read documentations

§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::boot function will be enough to initialize the Client. See foundationdb::api for more configuration options of the Fdb Client.

§Migration from 0.4 to 0.5

The initialization of foundationdb API has changed due to undefined behavior being possible with only safe code (issues #170, #181, pulls #179, #182).

Previously you had to wrote foundationdb::boot().expect("failed to initialize Fdb");, now this can be converted to:

// Safe because drop is called before the program exits
let network = unsafe { foundationdb::boot() };

// do stuff

// cleanly 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
  • directory
    Directory provides a tool for managing related subspaces.
  • fdb_keys
    Definitions of FDBKeys, used in api version 700 and more.
  • future
    Most functions in the FoundationDB API are asynchronous, meaning that they may return to the caller before actually delivering their Fdbresult.
  • mapped_key_values
    Definitions of MappedKeyValues, used in api version 710 and more.
  • options
    Generated configuration types for use with the various set_option functions
  • tenant
    Implementation of the Tenants API. Experimental features exposed through the tenant-experimental feature.
  • 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.
  • MaybeCommitted
    Wrapper around the boolean representing whether the previous transaction is still on fly This wrapper prevents the boolean to be copy and force it to be moved instead. This pretty handy when you don’t want to see the Database::run closure capturing the environment.
  • RangeOption
    RangeOption represents a query parameters for range scan query.
  • RetryableTransaction
    A retryable transaction, generated by Database.run
  • 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.

Enums§

  • FdbBindingError
    This error represent all errors that can be throwed by db.run. Layer developers may use the CustomError.

Traits§

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 Aliases§