0
# FoundationDB
1
2
FoundationDB is a distributed ACID 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, providing strong consistency guarantees with high performance and horizontal scalability.
3
4
## Package Information
5
6
- **Package Name**: foundationdb
7
- **Package Type**: Distributed Database System
8
- **Languages**: C (core), Python, Java, Go, Ruby
9
- **Version**: 7.4.3
10
- **License**: Apache-2.0
11
- **Documentation**: https://apple.github.io/foundationdb/
12
- **Installation**: Binary packages available at https://github.com/apple/foundationdb/releases
13
14
## Core Architecture
15
16
FoundationDB uses a layered architecture:
17
18
- **Core C Library**: Native database client interface (`libfdb_c`)
19
- **Language Bindings**: High-level APIs for Python, Java, Go, Ruby
20
- **Network Layer**: Handles cluster communication and failover
21
- **Transaction Engine**: ACID transactions with automatic conflict detection
22
- **Storage Engine**: Distributed key-value storage with replication
23
24
## Basic Usage Patterns
25
26
All FoundationDB bindings follow consistent patterns:
27
28
1. **API Version Selection**: Set API version before any operations
29
2. **Database Connection**: Open database from cluster file or connection string
30
3. **Transactional Operations**: All operations within ACID transactions
31
4. **Automatic Retries**: Built-in conflict detection and retry logic
32
5. **Asynchronous Operations**: Future-based async result handling
33
34
## Common Transaction Pattern
35
36
```python
37
# Python example (similar patterns in all languages)
38
import fdb
39
40
fdb.api_version(740)
41
db = fdb.open()
42
43
@fdb.transactional
44
def update_account_balance(tr, account_id, amount):
45
balance_key = f"account:{account_id}:balance"
46
current_balance = tr.get(balance_key).wait()
47
if current_balance is None:
48
current_balance = 0
49
else:
50
current_balance = int(current_balance)
51
52
new_balance = current_balance + amount
53
tr.set(balance_key, str(new_balance).encode())
54
return new_balance
55
56
# Automatically retried on conflicts
57
new_balance = update_account_balance(db, "user123", 100)
58
```
59
60
## Key Features
61
62
- **ACID Transactions**: Full transactional semantics across distributed operations
63
- **Multi-Version Concurrency Control (MVCC)**: High concurrency without blocking
64
- **Automatic Sharding**: Data automatically distributed and balanced
65
- **Fault Tolerance**: Built-in replication and automatic failover
66
- **Multi-Language Support**: Consistent APIs across 5 programming languages
67
- **Multi-Tenancy**: Isolated key spaces for different applications
68
- **Tuple Encoding**: Structured key encoding for hierarchical data
69
- **Directory Layer**: Hierarchical namespace management
70
71
## Capabilities
72
73
### C API (Core Interface)
74
75
The native C API provides the foundational interface to FoundationDB, offering direct control over network management, database connections, transactions, and asynchronous operations.
76
77
```c { .api }
78
// Network management
79
fdb_error_t fdb_select_api_version(int version);
80
fdb_error_t fdb_setup_network();
81
fdb_error_t fdb_run_network();
82
fdb_error_t fdb_stop_network();
83
84
// Database operations
85
fdb_error_t fdb_create_database(const char* cluster_file_path, FDBDatabase** out_database);
86
fdb_error_t fdb_database_create_transaction(FDBDatabase* database, FDBTransaction** out_transaction);
87
88
// Transaction operations
89
FDBFuture* fdb_transaction_get(FDBTransaction* tr, uint8_t const* key_name, int key_name_length, fdb_bool_t snapshot);
90
void fdb_transaction_set(FDBTransaction* tr, uint8_t const* key_name, int key_name_length, uint8_t const* value, int value_length);
91
FDBFuture* fdb_transaction_commit(FDBTransaction* tr);
92
```
93
94
[C API Reference](./c-api.md)
95
96
### Python API
97
98
High-level Python interface with decorator-based transaction handling, iterator support for ranges, and comprehensive error handling with Pythonic patterns.
99
100
```python { .api }
101
def api_version(version: int) -> None: ...
102
def open(cluster_file: Optional[str] = None) -> Database: ...
103
104
@transactional
105
def transaction_function(tr: Transaction) -> Any: ...
106
107
class Database:
108
def create_transaction(self) -> Transaction: ...
109
def open_tenant(self, tenant_name: bytes) -> Tenant: ...
110
111
class Transaction:
112
def get(self, key: KeyConvertible, snapshot: bool = False) -> Future: ...
113
def get_range(self, begin: KeyConvertible, end: KeyConvertible, limit: int = 0) -> Iterable[KeyValue]: ...
114
def set(self, key: KeyConvertible, value: ValueConvertible) -> None: ...
115
def clear(self, key: KeyConvertible) -> None: ...
116
def commit(self) -> Future: ...
117
```
118
119
[Python API Reference](./python-api.md)
120
121
### Java API
122
123
Object-oriented Java interface with CompletableFuture-based async operations, functional transaction interfaces, and comprehensive type safety.
124
125
```java { .api }
126
public class FDB {
127
public static FDB selectAPIVersion(int version);
128
public Database open();
129
public Database open(String clusterFilePath);
130
}
131
132
public interface Database {
133
Transaction createTransaction();
134
<T> T run(Function<Transaction, T> retryable);
135
<T> T read(Function<ReadTransaction, T> retryable);
136
Tenant openTenant(byte[] tenantName);
137
}
138
139
public interface Transaction extends ReadTransaction {
140
CompletableFuture<byte[]> get(byte[] key);
141
AsyncIterable<KeyValue> getRange(KeySelector begin, KeySelector end);
142
void set(byte[] key, byte[] value);
143
void clear(byte[] key);
144
CompletableFuture<Void> commit();
145
}
146
```
147
148
[Java API Reference](./java-api.md)
149
150
### Go API
151
152
Idiomatic Go interface with context support, interface-based design patterns, and channel-friendly async operations.
153
154
```go { .api }
155
func APIVersion(version int) error
156
func OpenDatabase(clusterFile string) (Database, error)
157
func StartNetwork() error
158
func StopNetwork() error
159
160
type Database interface {
161
CreateTransaction() (Transaction, error)
162
Transact(func(Transaction) (interface{}, error)) (interface{}, error)
163
ReadTransact(func(ReadTransaction) (interface{}, error)) (interface{}, error)
164
OpenTenant(tenantName []byte) (Tenant, error)
165
}
166
167
type Transaction interface {
168
Get(key KeyConvertible) Future
169
GetRange(r Range, options RangeOptions) RangeResult
170
Set(key, value KeyConvertible)
171
Clear(key KeyConvertible)
172
Commit() Future
173
}
174
```
175
176
[Go API Reference](./go-api.md)
177
178
### Ruby API
179
180
Ruby-native interface with block-based transaction handling, enumerable range iteration, and Ruby idioms for database operations.
181
182
```ruby { .api }
183
module FDB
184
def self.api_version(version)
185
def self.open(cluster_file = nil)
186
def self.transactional(&block)
187
188
class Database
189
def create_transaction
190
def transact(&block)
191
def open_tenant(tenant_name)
192
end
193
194
class Transaction
195
def get(key, snapshot: false)
196
def get_range(begin_key, end_key, options = {})
197
def []=(key, value) # Alias for set
198
def set(key, value)
199
def clear(key)
200
def commit
201
end
202
end
203
```
204
205
[Ruby API Reference](./ruby-api.md)
206
207
### Multi-Tenancy Support
208
209
Tenant-based isolation for multi-application deployments, providing separate key spaces while sharing the same database cluster.
210
211
```python { .api }
212
# Tenant operations (similar across all languages)
213
tenant = db.open_tenant(b"app1")
214
tenant_tr = tenant.create_transaction()
215
# All operations scoped to tenant keyspace
216
```
217
218
[Multi-Tenancy Guide](./multi-tenancy.md)
219
220
### Key Encoding and Utilities
221
222
Structured key encoding with tuple support and subspace management for organizing hierarchical data efficiently.
223
224
```python { .api }
225
import fdb.tuple as tuple
226
227
# Tuple encoding for structured keys
228
key = tuple.pack(("users", user_id, "profile"))
229
value = tuple.unpack(stored_key)
230
231
# Subspace for key prefixing
232
user_space = fdb.Subspace(("users",))
233
profile_key = user_space.pack((user_id, "profile"))
234
```
235
236
[Key Encoding and Subspaces](./key-encoding.md)
237
238
### Blob Granules
239
240
Advanced storage layer for large objects and historical data, providing cost-effective archival and analytical capabilities with separation of compute and storage.
241
242
```c { .api }
243
// Administrative blob operations (database level)
244
FDBFuture* fdb_database_blobbify_range(FDBDatabase* db, uint8_t const* begin_key, int begin_key_length,
245
uint8_t const* end_key, int end_key_length);
246
FDBFuture* fdb_database_purge_blob_granules(FDBDatabase* db, uint8_t const* begin_key, int begin_key_length,
247
uint8_t const* end_key, int end_key_length,
248
int64_t purge_version, fdb_bool_t force);
249
250
// Blob granule reading (transaction level)
251
FDBResult* fdb_transaction_read_blob_granules(FDBTransaction* tr, uint8_t const* begin_key, int begin_key_length,
252
uint8_t const* end_key, int end_key_length,
253
int64_t beginVersion, int64_t readVersion,
254
FDBReadBlobGranuleContext granuleContext);
255
```
256
257
[Blob Granules Reference](./blob-granules.md)
258
259
## Error Handling
260
261
FoundationDB provides consistent error handling across all language bindings with comprehensive error categorization and predicate functions.
262
263
### Error Categories
264
265
- **Retryable Errors**: Transaction conflicts that should be retried automatically
266
- **Maybe Committed Errors**: Transactions that may have succeeded despite errors
267
- **Fatal Errors**: Non-recoverable errors requiring application intervention
268
269
### Error Predicate Functions
270
271
All bindings provide predicate functions to categorize errors and determine appropriate retry strategies:
272
273
```python { .api }
274
# Python error predicates (fdb.predicates module)
275
def retryable(error: Exception) -> bool:
276
"""Check if error indicates transaction should be retried."""
277
278
def maybe_committed(error: Exception) -> bool:
279
"""Check if transaction may have been committed despite error."""
280
281
def retryable_not_committed(error: Exception) -> bool:
282
"""Check if error is retryable and transaction was not committed."""
283
```
284
285
```c { .api }
286
// C API error predicates
287
fdb_bool_t fdb_error_predicate(int predicate_test, fdb_error_t code);
288
289
// Predicate test constants
290
#define FDB_ERROR_PREDICATE_RETRYABLE 50000
291
#define FDB_ERROR_PREDICATE_MAYBE_COMMITTED 50001
292
#define FDB_ERROR_PREDICATE_RETRYABLE_NOT_COMMITTED 50002
293
```
294
295
### Common Error Codes
296
297
Key error codes across all language bindings:
298
299
- **1007** (`transaction_too_old`): Transaction read version too old
300
- **1020** (`not_committed`): Transaction was aborted
301
- **1021** (`commit_unknown_result`): Transaction may have been committed
302
- **1025** (`transaction_cancelled`): Transaction was cancelled
303
- **1031** (`future_version`): Version requested is too new
304
- **2131** (`tenant_not_found`): Specified tenant does not exist
305
- **2132** (`tenant_already_exists`): Tenant already exists in cluster
306
307
### Error Handling Patterns
308
309
```python
310
# Python automatic retry pattern
311
@fdb.transactional
312
def safe_operation(tr, key, value):
313
# Automatically retries on retryable errors
314
tr.set(key, value)
315
return tr.get(key).wait()
316
317
# Manual error handling
318
def manual_retry_operation(db, key, value):
319
tr = db.create_transaction()
320
while True:
321
try:
322
tr.set(key, value)
323
tr.commit().wait()
324
break
325
except fdb.FDBError as e:
326
if fdb.predicates.retryable(e):
327
tr.on_error(e).wait() # Wait for retry delay
328
continue
329
else:
330
raise # Non-retryable error
331
```
332
333
## Configuration Options
334
335
Three levels of configuration options:
336
337
- **Network Options**: Global client settings (TLS, tracing, external libraries)
338
- **Database Options**: Per-database settings (timeouts, cache sizes, location preferences)
339
- **Transaction Options**: Per-transaction settings (priorities, consistency levels, size limits)
340
341
## Types
342
343
```python { .api }
344
# Common types across bindings (Python syntax shown)
345
KeyConvertible = Union[bytes, str, tuple]
346
ValueConvertible = Union[bytes, str]
347
348
class KeyValue:
349
key: bytes
350
value: bytes
351
352
class KeySelector:
353
key: bytes
354
or_equal: bool
355
offset: int
356
357
class Future:
358
def wait(self) -> Any: ...
359
def is_ready(self) -> bool: ...
360
361
class FDBError(Exception):
362
code: int
363
description: str
364
```