FoundationDB

FoundationDB is a distributed, transactional key-value database designed to handle large volumes of structured data across clusters of commodity servers. It provides ACID transactions with strict serializability, automatic data distribution and rebalancing, and fault tolerance through replication.

Quick Start

import fdb

# Select API version (required first)
fdb.api_version(740)

# Open database connection
db = fdb.open()

# Use transactional decorator for automatic retry
@fdb.transactional
def set_value(tr, key, value):
    tr[key] = value
    return tr[key]

# Execute transaction
result = set_value(db, b'hello', b'world')

See Quick Start Guide for detailed setup instructions.

Package Information

• Package Name: foundationdb
• Version: 7.4.5
• Languages: Python, Go, Java, Ruby, C
• Installation:
  • Python: pip install foundationdb
  • Go: go get github.com/apple/foundationdb/bindings/go
  • Java: Maven dependency com.apple:foundationdb
  • Ruby: gem install fdb

Core Concepts

Transactions

All operations occur within ACID transactions providing serializable isolation. Use transactional wrappers (@transactional, Transact(), run()) for automatic retry on conflicts.

Future-Based Operations

Read operations return Future objects. Block explicitly to retrieve results (.wait(), .MustGet(), .join()).

Data Model Layers

• Tuple Layer: Type-safe encoding/decoding of structured keys
• Subspace Layer: Namespace isolation with key prefixing
• Directory Layer: Hierarchical directory system with automatic prefix allocation

Core Imports

import fdb

import "github.com/apple/foundationdb/bindings/go/src/fdb"

import com.apple.foundationdb.*;

require 'fdb'

#include <foundationdb/fdb_c.h>

API Quick Reference

Essential Operations

Transactional Wrappers

@fdb.transactional
def my_operation(tr, ...):
    tr[key] = value
    return result

db.Transact(func(tr fdb.Transaction) (interface{}, error) {
    tr.Set(key, value)
    return result, nil
})

db.run(tr -> {
    tr.set(key, value);
    return result;
});

Capabilities Overview

Error Handling

FoundationDB uses error codes for failures. Common codes:

• 1007 - transaction_too_old: Transaction exceeded maximum duration
• 1020 - not_committed: Transaction conflicted
• 1021 - commit_unknown_result: Commit status unknown

Use transactional wrappers for automatic retry on retryable errors.

Best Practices

1. Use Transactional Wrappers: Prefer @transactional, Transact(), run() over manual management
2. Keep Transactions Short: Complete within 5 seconds to avoid conflicts
3. Avoid Side Effects: Transaction functions may retry; keep them pure
4. Use Snapshot Reads: When serializability isn't needed
5. Structure Keys: Use Tuple layer for proper ordering
6. Namespace Isolation: Use Subspaces and Directories

Documentation Structure

Guides

• Quick Start Guide - Getting started with FoundationDB

Examples

• Real-World Scenarios - Comprehensive usage examples
• Edge Cases - Advanced scenarios and edge cases

Reference

• Python API Reference
• Go API Reference
• Java API Reference
• Ruby API Reference
• C API Reference
• Tuple Layer
• Subspace Layer
• Directory Layer

Resources

• Official Documentation
• API Reference
• Error Codes
• Data Modeling
• GitHub Repository