foundationdb 0.11.0

High level client bindings for FoundationDB.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

use byteorder::ByteOrder;
use foundationdb::api::FdbApiBuilder;
use foundationdb::options::NetworkOption;
use foundationdb::tuple::Subspace;
use foundationdb::{Database, FdbBindingError, options};

/// This example demonstrate usage of multi_version compatibility client.
///
/// While you still need to compile the crate with a specific FoundationDB library version,
/// it allows you to connect to a cluster with a different API version. Be aware that using
/// this feature might lead to divergent behaviors.
///
/// Ref: https://apple.github.io/foundationdb/api-general.html#multi-version-client-api
const NETWORK_OPTION_EXTERNAL_CLIENT_DIRECTORY: &str =
    "FDB_NETWORK_OPTION_EXTERNAL_CLIENT_DIRECTORY";

#[tokio::main]
async fn main() {
    let mut network_builder = FdbApiBuilder::default()
        .build()
        .expect("Failed to build API");
    // You can either use FoundationDB network option through environment variables
    // or through network options in code.
    // directory specified should contain at least one libfdb.so
    if std::env::var(NETWORK_OPTION_EXTERNAL_CLIENT_DIRECTORY).is_err() {
        network_builder = network_builder
            .set_option(NetworkOption::ExternalClientDirectory(
                "/usr/lib/foundationdb/".to_string(),
            ))
            .expect("Failed to add external library directory");
    }
    let _guard = unsafe { network_builder.boot() };

    // You can replace `None` with an `Option` with the path to your `fdb.cluster` file
    let db = Database::new_compat(None)
        .await
        .expect("failed to get database");
    db.set_option(options::DatabaseOption::TransactionTimeout(5000))
        .expect("failed to set transaction timeout");
    db.set_option(options::DatabaseOption::TransactionRetryLimit(3))
        .expect("failed to set transaction retry limit");

    // used to catch the first cluster_version_changed error when using external clients
    // when using external clients, it will throw cluster_version_changed for the first time establish the connection to
    // the cluster. Thus, we catch it by doing a get version request to establish the connection
    // The 3000ms timeout is a guard to avoid waiting forever when the cli cannot talk to any coordinators
    let _ = db
        .run(|trx, _| async move {
            trx.set_option(options::TransactionOption::Timeout(3000))?;
            let maybe_version = trx.get_read_version().await;

            match maybe_version {
                Ok(_) => Ok(()),
                // 1039: cluster_version_changed
                Err(err) if err.code() == 1039 => Err(FdbBindingError::from(err)),
                Err(err) => Err(FdbBindingError::NonRetryableFdbError(err)),
            }
        })
        .await;

    let key = Subspace::all()
        .subspace(&"examples")
        .pack(&"multi_version_incr");

    // increment or create key with "1"
    db.run(|trx, _| {
        let key = key.clone();
        async move {
            let mut buf = [0u8; 8];
            byteorder::LE::write_i64(&mut buf, 1);
            trx.atomic_op(&key, &buf, options::MutationType::Add);
            Ok(())
        }
    })
    .await
    .expect("could not commit");

    // read counter value
    let raw_counter = db
        .run(|trx, _| {
            let key = key.clone();
            async move {
                let result = trx.get(&key, true).await?;
                Ok(result)
            }
        })
        .await
        .expect("could not read key")
        .expect("no value found");

    let counter = byteorder::LE::read_i64(raw_counter.as_ref());
    dbg!(counter);
    assert!(counter > 0);
}