FeOxDB

FeOxDB provides ACI (Atomicity, Consistency, Isolation) properties but uses a relaxed durability model to achieve extreme performance. It employs write-behind logging, meaning data is not immediately flushed to disk.

Durability Characteristics

• Atomicity: Individual operations are atomic via Arc-wrapped records.
• Consistency: Timestamp-based conflict resolution.
• Isolation: Lock-free reads and sharded writes.
• Durability (Relaxed): Writes are buffered and flushed every 100ms or when buffers reach 1024 entries or 16MB per shard.

Managing Durability

• Memory-only mode: Provides no durability.
• Maximum Performance: Use the default write-behind buffering for derived data or caches that can be rebuilt.
• Stronger Guarantees: To achieve fsync-level durability for critical operations, call store.flush(). This method blocks until the buffered data is synchronously written to disk.

FeOxDB v0.6.0 uses storage format v3, which includes checksummed metadata, allocation journaling, and recoverable deletion markers. Format v1 and v2 stores can be opened in compatibility mode, but they are not automatically converted to v3.

To upgrade a store, you must perform an offline, copy-only migration using the feox-migrate binary.

Important Migration Rules:

• The source must be opened read-only.
• The destination file must not already exist.
• Stop all processes using the source before migrating.
• Migration is not an in-place operation.
• Ambiguous Legacy Markers: If a legacy deletion marker lacks extent length, migration may fail. You can bypass this using the --allow-ambiguous-legacy-recovery flag, but be aware this may interpret deleted data as live records.

# Install the migration tool
cargo install feoxdb --version 0.6.0 --bin feox-migrate

# Perform the migration
feox-migrate --source data-v2.feox --destination data-v3.feox

The test_hooks module provides deterministic interleaving hooks used to simulate failures and control thread execution order during tests. These hooks are only active when compiled with cfg(test).

There are two primary mechanisms:

1. pause_at(point): Blocks the current thread at a specific named point until a test releases it or a timeout occurs. This allows a test to hold a thread at a specific instruction boundary to drive other threads past it.
2. fail_at(point, scope): Returns true if a fault has been armed for the specified point and scope, allowing the caller to simulate a failure (e.g., a crash or error return).

Commonly used points include:

• AFTER_SECTOR_LOAD
• RECORD_WRITE
• AFTER_UPSERT_READ
• AFTER_JSON_PATCH_READ
• AFTER_TTL_DEFERRED_SOURCE (test only)
• AFTER_CACHE_BUCKET_CLEAR (test only)
• TTL_AFTER_EXPIRED_SAMPLE (test only)

// Example of using pause_at and fail_at in a test context
// Note: These are only functional when running in test mode

// In the code being tested:
pause_at("record_write");
if fail_at("record_write", scope) {
    return Err(DatabaseError::Simulated);
}

// In the test itself:
let scope = new_fault_scope();
// ... logic to arm the fault ...

The WriteBuffer is designed for high-concurrency environments using several key strategies:

• Sharding: Writes are distributed across multiple ShardedWriteBuffer instances based on the hash of the record key. This minimizes lock contention between threads.
• Background Workers: A pool of worker threads processes these shards. Each worker is responsible for a subset of shards, which maintains write ordering for specific keys.
• Durability via Journaling: During a batch write, the system uses an allocation journal. It first records the intent to allocate sectors, performs the write, and then clears the journal. This protects against indeterminate states during crashes.
• Retirement Queue: Deletions are not processed immediately with writes. Instead, they are moved to a RetirementQueue to be handled as a separate phase, ensuring that space is only released after the corresponding record deletions are durable.

The ClockCache is a cache implementation using the CLOCK algorithm (a common approximation of LRU) for efficient record eviction. It uses reference bits and circular scanning to decide which entries to evict when memory usage hits a high watermark.

Key behaviors:

• Eviction: When the cache exceeds the high_watermark, it triggers an eviction process that scans entries and removes those without a recent reference bit until the low_watermark is reached.
• Memory Management: It tracks memory usage via cache_memory statistics. Very large values (exceeding 1/4 of the high watermark) are automatically excluded from being cached.
• Concurrency: The cache is organized into buckets to reduce lock contention, using RwLock for bucket access and an AtomicUsize for the global clock hand.

To use it, initialize it with a shared Statistics object.

// Initialization requires an Arc<Statistics>
let cache = ClockCache::new(stats);