0
# FoundationDB
1

2
FoundationDB 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.
3

4
## Package Information
5

6
- **Package Name**: foundationdb
7
- **Package Type**: distributed database system
8
- **Languages**: C, Python, Java, Go, Ruby
9
- **Installation**: Available via binary packages at https://www.foundationdb.org/download/
10
- **Documentation**: https://apple.github.io/foundationdb/
11

12
## Architecture
13

14
FoundationDB employs a unique architecture that separates compute and storage:
15

16
- **Client Libraries**: Language-specific bindings that provide native APIs
17
- **Database Process**: Stateless transaction processing layer  
18
- **Storage Process**: Distributed key-value storage with automatic sharding
19
- **Cluster Controller**: Coordinates cluster membership and configuration
20
- **Sequencer**: Provides global transaction ordering for ACID compliance
21

22
The multi-version concurrency control (MVCC) system enables non-blocking reads while maintaining serializable transactions across the entire distributed system.
23

24
## Core Imports
25

26
### C API
27

28
```c
29
#define FDB_API_VERSION 630
30
#include <foundationdb/fdb_c.h>
31
```
32

33
### Python API
34

35
```python
36
import fdb
37
```
38

39
For specific components:
40

41
```python
42
from fdb import directory
43
from fdb.subspace_impl import Subspace
44
```
45

46
### Java API
47

48
```java
49
import com.apple.foundationdb.*;
50
import com.apple.foundationdb.tuple.Tuple;
51
```
52

53
### Go API
54

55
```go
56
import "github.com/apple/foundationdb/bindings/go/src/fdb"
57
import "github.com/apple/foundationdb/bindings/go/src/fdb/subspace"
58
import "github.com/apple/foundationdb/bindings/go/src/fdb/directory"
59
```
60

61
### Ruby API
62

63
```ruby
64
require 'fdb'
65
```
66

67
## Basic Usage
68

69
### C API
70

71
```c
72
#define FDB_API_VERSION 630
73
#include <foundationdb/fdb_c.h>
74

75
int main() {
76
    fdb_select_api_version(630);
77
    fdb_setup_network();
78
    
79
    // Start network thread in background
80
    
81
    FDBDatabase* db;
82
    fdb_create_database(NULL, &db);
83
    
84
    FDBTransaction* tr;
85
    fdb_database_create_transaction(db, &tr);
86
    
87
    // Set a key-value pair
88
    const char* key = "hello";
89
    const char* value = "world";
90
    fdb_transaction_set(tr, (const uint8_t*)key, strlen(key), 
91
                        (const uint8_t*)value, strlen(value));
92
    
93
    // Commit transaction
94
    FDBFuture* commit_future = fdb_transaction_commit(tr);
95
    fdb_future_block_until_ready(commit_future);
96
    
97
    // Cleanup
98
    fdb_future_destroy(commit_future);
99
    fdb_transaction_destroy(tr);
100
    fdb_database_destroy(db);
101
    fdb_stop_network();
102
    
103
    return 0;
104
}
105
```
106

107
### Python API
108

109
```python
110
import fdb
111

112
# Required before any other fdb calls
113
fdb.api_version(630)
114

115
# Open database
116
db = fdb.open()
117

118
# Transactional function
119
@fdb.transactional
120
def set_and_get(tr, key, value):
121
    tr.set(key, value)
122
    return tr.get(key)
123

124
# Execute transaction
125
result = set_and_get(db, b"hello", b"world")
126
print(result)  # b"world"
127
```
128

129
### Java API
130

131
```java
132
import com.apple.foundationdb.*;
133

134
public class Example {
135
    public static void main(String[] args) {
136
        FDB fdb = FDB.selectAPIVersion(630);
137
        
138
        try (Database db = fdb.open()) {
139
            // Synchronous transaction
140
            String result = db.run(tr -> {
141
                tr.set(Tuple.from("hello").pack(), Tuple.from("world").pack());
142
                return new String(tr.get(Tuple.from("hello").pack()).join());
143
            });
144
            
145
            System.out.println(result);
146
        }
147
    }
148
}
149
```
150

151
### Go API
152

153
```go
154
package main
155

156
import (
157
    "fmt"
158
    "github.com/apple/foundationdb/bindings/go/src/fdb"
159
)
160

161
func main() {
162
    fdb.MustAPIVersion(630)
163
    
164
    db := fdb.MustOpenDefault()
165
    
166
    // Transactional function
167
    result, err := db.Transact(func(tr fdb.Transaction) (interface{}, error) {
168
        tr.Set(fdb.Key("hello"), []byte("world"))
169
        return tr.Get(fdb.Key("hello")).MustGet(), nil
170
    })
171
    
172
    if err != nil {
173
        panic(err)
174
    }
175
    
176
    fmt.Println(string(result.([]byte))) // "world"
177
}
178
```
179

180
## Capabilities
181

182
### Core Database Operations
183

184
Fundamental database operations including connecting to clusters, creating transactions, and performing CRUD operations with ACID guarantees.
185

186
```c { .api }
187
// C API
188
fdb_error_t fdb_select_api_version_impl(int runtime_version, int header_version);
189
fdb_error_t fdb_create_database(const char* cluster_file_path, FDBDatabase** out_database);
190
fdb_error_t fdb_database_create_transaction(FDBDatabase* d, FDBTransaction** out_transaction);
191
```
192

193
```python { .api }
194
# Python API
195
def api_version(version: int) -> None: ...
196
def open(cluster_file: str = None, event_model: str = None) -> Database: ...
197
```
198

199
[Core Operations](./core-operations.md)
200

201
### Transaction Management
202

203
Transaction lifecycle management including creation, execution, error handling, and retry logic with optimistic concurrency control.
204

205
```c { .api }
206
// C API  
207
FDBFuture* fdb_transaction_commit(FDBTransaction* tr);
208
FDBFuture* fdb_transaction_on_error(FDBTransaction* tr, fdb_error_t error);
209
void fdb_transaction_reset(FDBTransaction* tr);
210
void fdb_transaction_cancel(FDBTransaction* tr);
211
```
212

213
```python { .api }
214
# Python API
215
def transactional(func: Callable) -> Callable: ...
216

217
class Transaction:
218
    def commit(self) -> Future: ...
219
    def on_error(self, error: FDBError) -> Future: ...
220
    def reset(self) -> None: ...
221
    def cancel(self) -> None: ...
222
```
223

224
[Transaction Management](./transactions.md)
225

226
### Key-Value Operations  
227

228
Reading and writing key-value pairs with support for atomic operations, range queries, and watches for change notifications.
229

230
```c { .api }
231
// C API
232
FDBFuture* fdb_transaction_get(FDBTransaction* tr, uint8_t const* key_name, 
233
                               int key_name_length, fdb_bool_t snapshot);
234
void fdb_transaction_set(FDBTransaction* tr, uint8_t const* key_name, int key_name_length,
235
                         uint8_t const* value, int value_length);
236
void fdb_transaction_clear(FDBTransaction* tr, uint8_t const* key_name, int key_name_length);
237
FDBFuture* fdb_transaction_get_range(FDBTransaction* tr, /* range parameters */);
238
```
239

240
```python { .api }  
241
# Python API
242
class Transaction:
243
    def get(self, key: bytes, snapshot: bool = False) -> Future: ...
244
    def set(self, key: bytes, value: bytes) -> None: ...
245
    def clear(self, key: bytes) -> None: ...
246
    def get_range(self, begin: KeySelector, end: KeySelector, **kwargs) -> FDBRange: ...
247
```
248

249
[Key-Value Operations](./key-value-ops.md)
250

251
### Atomic Operations
252

253
Atomic read-modify-write operations for counters, bit manipulation, and other compound operations that execute atomically.
254

255
```c { .api }
256
// C API
257
void fdb_transaction_atomic_op(FDBTransaction* tr, uint8_t const* key_name, 
258
                               int key_name_length, uint8_t const* param, 
259
                               int param_length, FDBMutationType operation_type);
260
```
261

262
```python { .api }
263
# Python API  
264
class Transaction:
265
    def atomic_op(self, key: bytes, param: bytes, mutation_type: int) -> None: ...
266
    def add(self, key: bytes, value: bytes) -> None: ...
267
    def bit_and(self, key: bytes, value: bytes) -> None: ...
268
    def bit_or(self, key: bytes, value: bytes) -> None: ...
269
    def bit_xor(self, key: bytes, value: bytes) -> None: ...
270
```
271

272
[Atomic Operations](./atomic-operations.md)
273

274
### Configuration and Options
275

276
Network, database, and transaction-level configuration options for performance tuning, security, and operational behavior.
277

278
```c { .api }
279
// C API
280
fdb_error_t fdb_network_set_option(FDBNetworkOption option, uint8_t const* value, int value_length);
281
fdb_error_t fdb_database_set_option(FDBDatabase* d, FDBDatabaseOption option, 
282
                                    uint8_t const* value, int value_length);
283
fdb_error_t fdb_transaction_set_option(FDBTransaction* tr, FDBTransactionOption option,
284
                                       uint8_t const* value, int value_length);
285
```
286

287
```python { .api }
288
# Python API
289
class NetworkOptions:
290
    def set_trace_enable(self, path: str) -> None: ...
291
    def set_tls_cert_path(self, path: str) -> None: ...
292

293
class DatabaseOptions:  
294
    def set_location_cache_size(self, size: int) -> None: ...
295
    def set_max_watches(self, count: int) -> None: ...
296

297
class TransactionOptions:
298
    def set_timeout(self, milliseconds: int) -> None: ...
299
    def set_retry_limit(self, count: int) -> None: ...
300
```
301

302
[Configuration](./configuration.md)
303

304
### Directory Layer
305

306
Hierarchical directory abstraction for organizing keys into namespaces with automatic prefix management and metadata.
307

308
```python { .api }  
309
# Python API
310
class DirectoryLayer:
311
    def create_or_open(self, tr: Transaction, path: List[str], **kwargs) -> DirectorySubspace: ...
312
    def open(self, tr: Transaction, path: List[str], **kwargs) -> DirectorySubspace: ...
313
    def create(self, tr: Transaction, path: List[str], **kwargs) -> DirectorySubspace: ...
314
    def move(self, tr: Transaction, old_path: List[str], new_path: List[str]) -> DirectorySubspace: ...
315
    def remove(self, tr: Transaction, path: List[str]) -> bool: ...
316
    def list(self, tr: Transaction, path: List[str] = []) -> List[str]: ...
317

318
class DirectorySubspace(Subspace):
319
    def get_path(self) -> List[str]: ...
320
    def get_layer(self) -> bytes: ...
321
```
322

323
[Directory Layer](./directory-layer.md)
324

325
### Subspace Operations
326

327
Key space partitioning with tuple encoding for structured data organization and automatic prefix management.
328

329
```python { .api }
330
# Python API  
331
class Subspace:
332
    def __init__(self, prefix: bytes = b'', tuple: tuple = ()): ...
333
    def key(self) -> bytes: ...
334
    def pack(self, tuple: tuple) -> bytes: ...
335
    def unpack(self, key: bytes) -> tuple: ...
336
    def contains(self, key: bytes) -> bool: ...
337
    def subspace(self, tuple: tuple) -> 'Subspace': ...
338
    def range(self, tuple: tuple = ()) -> Range: ...
339
```
340

341
[Subspaces](./subspaces.md)
342

343
## Error Handling
344

345
FoundationDB uses error codes for exceptional conditions. Errors may indicate retryable conditions (like conflicts) or permanent failures.
346

347
```c { .api }
348
// C API
349
typedef int fdb_error_t;
350
const char* fdb_get_error(fdb_error_t code);
351
fdb_bool_t fdb_error_predicate(int predicate_test, fdb_error_t code);
352
```
353

354
```python { .api }
355
# Python API
356
class FDBError(Exception):
357
    code: int
358
    description: str
359

360
class ErrorPredicates:
361
    def retryable(self, error: FDBError) -> bool: ...
362
    def maybe_committed(self, error: FDBError) -> bool: ...
363
    def retryable_not_committed(self, error: FDBError) -> bool: ...
364
```
365

366
Common error codes:
367
- `1020` - Transaction not committed
368
- `1021` - Transaction may have committed  
369
- `1025` - Transaction cancelled
370
- `1031` - Transaction timed out
371
- `1007` - Transaction too old
372
- `1009` - Future version