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
```