13 releases (breaking)
0.9.1 | Oct 8, 2024 |
---|---|
0.9.0 | Mar 15, 2024 |
0.8.0 | Jun 8, 2023 |
0.7.0 | Jul 11, 2022 |
0.2.0 | May 9, 2018 |
#15 in Database interfaces
608,541 downloads per month
Used in 19 crates
(10 directly)
405KB
6.5K
SLoC
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.71.1 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.
Platform | Tier | Notes |
---|---|---|
linux x86_64 | 1 | |
osx x86_64 | 2 | |
Windows x86_64 | 3 | Windows build has been officially discontinue, now maintained by the community |
osx Silicon | 3 | Waiting for official dylib support |
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
Features | Notes |
---|---|
fdb-5_1 |
Support for FoundationDB 5.1.X |
fdb-5_2 |
Support for FoundationDB 5.2.X |
fdb-6_0 |
Support for FoundationDB 6.0.X |
fdb-6_1 |
Support for FoundationDB 6.1.X |
fdb-6_2 |
Support for FoundationDB 6.2.X |
fdb-6_3 |
Support for FoundationDB 6.3.X |
fdb-7_0 |
Support for FoundationDB 7.0.X |
fdb-7_1 |
Support for FoundationDB 7.1.X |
embedded-fdb-include |
Use the locally embedded FoundationDB fdb_c.h and fdb.options files to compile |
uuid |
Support for the uuid crate for Tuples |
num-bigint |
Support for the bigint crate for Tuples |
tenant-experimental |
Experimental 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.
Dependencies
~1.5–4.5MB
~87K SLoC