FoundationDB is a distributed database designed to handle large volumes of structured data across clusters with ACID transactions.
pkg:github/apple/foundationdb@6.3.x
npx @tessl/cli install tessl/github-foundationdb@6.3.0FoundationDB is a distributed database designed to handle large volumes of structured data across clusters of commodity servers. It organizes data as an ordered key-value store and employs ACID transactions for all operations. It is especially well-suited for read/write workloads with excellent performance for write-intensive workloads, providing strict consistency guarantees and horizontal scalability.
FoundationDB employs a unique architecture that separates compute and storage:
The multi-version concurrency control (MVCC) system enables non-blocking reads while maintaining serializable transactions across the entire distributed system.
#define FDB_API_VERSION 630
#include <foundationdb/fdb_c.h>import fdbFor specific components:
from fdb import directory
from fdb.subspace_impl import Subspaceimport com.apple.foundationdb.*;
import com.apple.foundationdb.tuple.Tuple;import "github.com/apple/foundationdb/bindings/go/src/fdb"
import "github.com/apple/foundationdb/bindings/go/src/fdb/subspace"
import "github.com/apple/foundationdb/bindings/go/src/fdb/directory"require 'fdb'#define FDB_API_VERSION 630
#include <foundationdb/fdb_c.h>
int main() {
fdb_select_api_version(630);
fdb_setup_network();
// Start network thread in background
FDBDatabase* db;
fdb_create_database(NULL, &db);
FDBTransaction* tr;
fdb_database_create_transaction(db, &tr);
// Set a key-value pair
const char* key = "hello";
const char* value = "world";
fdb_transaction_set(tr, (const uint8_t*)key, strlen(key),
(const uint8_t*)value, strlen(value));
// Commit transaction
FDBFuture* commit_future = fdb_transaction_commit(tr);
fdb_future_block_until_ready(commit_future);
// Cleanup
fdb_future_destroy(commit_future);
fdb_transaction_destroy(tr);
fdb_database_destroy(db);
fdb_stop_network();
return 0;
}import fdb
# Required before any other fdb calls
fdb.api_version(630)
# Open database
db = fdb.open()
# Transactional function
@fdb.transactional
def set_and_get(tr, key, value):
tr.set(key, value)
return tr.get(key)
# Execute transaction
result = set_and_get(db, b"hello", b"world")
print(result) # b"world"import com.apple.foundationdb.*;
public class Example {
public static void main(String[] args) {
FDB fdb = FDB.selectAPIVersion(630);
try (Database db = fdb.open()) {
// Synchronous transaction
String result = db.run(tr -> {
tr.set(Tuple.from("hello").pack(), Tuple.from("world").pack());
return new String(tr.get(Tuple.from("hello").pack()).join());
});
System.out.println(result);
}
}
}package main
import (
"fmt"
"github.com/apple/foundationdb/bindings/go/src/fdb"
)
func main() {
fdb.MustAPIVersion(630)
db := fdb.MustOpenDefault()
// Transactional function
result, err := db.Transact(func(tr fdb.Transaction) (interface{}, error) {
tr.Set(fdb.Key("hello"), []byte("world"))
return tr.Get(fdb.Key("hello")).MustGet(), nil
})
if err != nil {
panic(err)
}
fmt.Println(string(result.([]byte))) // "world"
}Fundamental database operations including connecting to clusters, creating transactions, and performing CRUD operations with ACID guarantees.
// C API
fdb_error_t fdb_select_api_version_impl(int runtime_version, int header_version);
fdb_error_t fdb_create_database(const char* cluster_file_path, FDBDatabase** out_database);
fdb_error_t fdb_database_create_transaction(FDBDatabase* d, FDBTransaction** out_transaction);# Python API
def api_version(version: int) -> None: ...
def open(cluster_file: str = None, event_model: str = None) -> Database: ...Transaction lifecycle management including creation, execution, error handling, and retry logic with optimistic concurrency control.
// C API
FDBFuture* fdb_transaction_commit(FDBTransaction* tr);
FDBFuture* fdb_transaction_on_error(FDBTransaction* tr, fdb_error_t error);
void fdb_transaction_reset(FDBTransaction* tr);
void fdb_transaction_cancel(FDBTransaction* tr);# Python API
def transactional(func: Callable) -> Callable: ...
class Transaction:
def commit(self) -> Future: ...
def on_error(self, error: FDBError) -> Future: ...
def reset(self) -> None: ...
def cancel(self) -> None: ...Reading and writing key-value pairs with support for atomic operations, range queries, and watches for change notifications.
// C API
FDBFuture* fdb_transaction_get(FDBTransaction* tr, uint8_t const* key_name,
int key_name_length, fdb_bool_t snapshot);
void fdb_transaction_set(FDBTransaction* tr, uint8_t const* key_name, int key_name_length,
uint8_t const* value, int value_length);
void fdb_transaction_clear(FDBTransaction* tr, uint8_t const* key_name, int key_name_length);
FDBFuture* fdb_transaction_get_range(FDBTransaction* tr, /* range parameters */);# Python API
class Transaction:
def get(self, key: bytes, snapshot: bool = False) -> Future: ...
def set(self, key: bytes, value: bytes) -> None: ...
def clear(self, key: bytes) -> None: ...
def get_range(self, begin: KeySelector, end: KeySelector, **kwargs) -> FDBRange: ...Atomic read-modify-write operations for counters, bit manipulation, and other compound operations that execute atomically.
// C API
void fdb_transaction_atomic_op(FDBTransaction* tr, uint8_t const* key_name,
int key_name_length, uint8_t const* param,
int param_length, FDBMutationType operation_type);# Python API
class Transaction:
def atomic_op(self, key: bytes, param: bytes, mutation_type: int) -> None: ...
def add(self, key: bytes, value: bytes) -> None: ...
def bit_and(self, key: bytes, value: bytes) -> None: ...
def bit_or(self, key: bytes, value: bytes) -> None: ...
def bit_xor(self, key: bytes, value: bytes) -> None: ...Network, database, and transaction-level configuration options for performance tuning, security, and operational behavior.
// C API
fdb_error_t fdb_network_set_option(FDBNetworkOption option, uint8_t const* value, int value_length);
fdb_error_t fdb_database_set_option(FDBDatabase* d, FDBDatabaseOption option,
uint8_t const* value, int value_length);
fdb_error_t fdb_transaction_set_option(FDBTransaction* tr, FDBTransactionOption option,
uint8_t const* value, int value_length);# Python API
class NetworkOptions:
def set_trace_enable(self, path: str) -> None: ...
def set_tls_cert_path(self, path: str) -> None: ...
class DatabaseOptions:
def set_location_cache_size(self, size: int) -> None: ...
def set_max_watches(self, count: int) -> None: ...
class TransactionOptions:
def set_timeout(self, milliseconds: int) -> None: ...
def set_retry_limit(self, count: int) -> None: ...Hierarchical directory abstraction for organizing keys into namespaces with automatic prefix management and metadata.
# Python API
class DirectoryLayer:
def create_or_open(self, tr: Transaction, path: List[str], **kwargs) -> DirectorySubspace: ...
def open(self, tr: Transaction, path: List[str], **kwargs) -> DirectorySubspace: ...
def create(self, tr: Transaction, path: List[str], **kwargs) -> DirectorySubspace: ...
def move(self, tr: Transaction, old_path: List[str], new_path: List[str]) -> DirectorySubspace: ...
def remove(self, tr: Transaction, path: List[str]) -> bool: ...
def list(self, tr: Transaction, path: List[str] = []) -> List[str]: ...
class DirectorySubspace(Subspace):
def get_path(self) -> List[str]: ...
def get_layer(self) -> bytes: ...Key space partitioning with tuple encoding for structured data organization and automatic prefix management.
# Python API
class Subspace:
def __init__(self, prefix: bytes = b'', tuple: tuple = ()): ...
def key(self) -> bytes: ...
def pack(self, tuple: tuple) -> bytes: ...
def unpack(self, key: bytes) -> tuple: ...
def contains(self, key: bytes) -> bool: ...
def subspace(self, tuple: tuple) -> 'Subspace': ...
def range(self, tuple: tuple = ()) -> Range: ...FoundationDB uses error codes for exceptional conditions. Errors may indicate retryable conditions (like conflicts) or permanent failures.
// C API
typedef int fdb_error_t;
const char* fdb_get_error(fdb_error_t code);
fdb_bool_t fdb_error_predicate(int predicate_test, fdb_error_t code);# Python API
class FDBError(Exception):
code: int
description: str
class ErrorPredicates:
def retryable(self, error: FDBError) -> bool: ...
def maybe_committed(self, error: FDBError) -> bool: ...
def retryable_not_committed(self, error: FDBError) -> bool: ...Common error codes:
1020 - Transaction not committed1021 - Transaction may have committed1025 - Transaction cancelled1031 - Transaction timed out1007 - Transaction too old1009 - Future version