WAL Quick Reference Guide

WAL Quick Reference Guide

Configuration

Enable WAL

config.toml

[storage]
wal_enabled = true
wal_sync_mode = "sync"  # Options: "sync", "async", "group_commit"

// Programmatic
let mut config = Config::default();
config.storage.wal_enabled = true;
config.storage.wal_sync_mode = WalSyncModeConfig::Sync;

Sync Modes

Mode	Fsync	Throughput	Latency	Durability	Use Case
Sync	Every	~1K ops/s	1-5ms	Maximum	Production
Async	OS	~100K ops/s	<1ms	OS-level	Testing/Dev
GroupCommit	Batched	~50K ops/s	1-2ms	High	High-throughput

Common Operations

Check WAL Status

// Is WAL enabled?
if engine.is_wal_enabled() {
    println!("WAL is active");
}

// Get current LSN
let lsn = engine.wal_lsn().unwrap_or(0);
println!("Current LSN: {}", lsn);

// Get sync mode
if let Some(mode) = engine.wal_sync_mode() {
    println!("Sync mode: {:?}", mode);
}

Flush WAL

// Force fsync (for async/group_commit modes)
engine.flush_wal()?;

Change Sync Mode

// Switch to async mode at runtime
engine.set_wal_sync_mode(WalSyncMode::Async)?;

// Switch to sync mode for critical operation
engine.set_wal_sync_mode(WalSyncMode::Sync)?;

Crash Recovery

// Open engine (auto-recovers LSN)
let engine = StorageEngine::open("./data", &config)?;

// Replay WAL entries if needed
let recovered = engine.replay_wal()?;
println!("Recovered {} operations", recovered);

Truncate WAL (Checkpointing)

// After successful checkpoint at LSN 10000
let checkpoint_lsn = 10000;
engine.truncate_wal(checkpoint_lsn)?;

Write Operations (Automatic WAL Logging)

// All writes automatically log to WAL first
engine.put(b"key", b"value")?;      // → WAL append, then RocksDB put
engine.delete(b"key")?;              // → WAL append, then RocksDB delete
engine.insert_tuple("users", tuple)?; // → WAL append, then insert

Graceful Shutdown

// Ensure all data is flushed before shutdown
engine.flush_wal()?;  // Flush WAL
engine.flush()?;      // Flush RocksDB
engine.close()?;      // Close engine

Best Practices

1. Production Configuration

config.storage.wal_enabled = true;
config.storage.wal_sync_mode = WalSyncModeConfig::Sync;

2. Periodic Checkpointing

const CHECKPOINT_INTERVAL: u64 = 10000;

if engine.wal_lsn().unwrap_or(0) % CHECKPOINT_INTERVAL == 0 {
    let lsn = engine.wal_lsn().unwrap();
    engine.flush()?;  // Checkpoint
    engine.truncate_wal(lsn - CHECKPOINT_INTERVAL)?;  // Cleanup
}

3. Monitor WAL Size

let lsn = engine.wal_lsn().unwrap_or(0);
if lsn > 100000 {
    warn!("WAL has {} entries, consider checkpointing", lsn);
}

4. Development/Testing

// Use async mode for faster tests
config.storage.wal_sync_mode = WalSyncModeConfig::Async;

Troubleshooting

WAL not enabled

if !engine.is_wal_enabled() {
    // Check config.storage.wal_enabled = true
    // Check for initialization errors in logs
}

High write latency

// Switch to async or group_commit mode
engine.set_wal_sync_mode(WalSyncMode::GroupCommit)?;

Large WAL size

// Implement checkpointing
let lsn = engine.wal_lsn().unwrap();
engine.flush()?;
engine.truncate_wal(lsn - 10000)?;

Performance Tips

1. Use Sync mode for durability: Maximum safety, ~1K writes/sec
2. Use GroupCommit for throughput: Balanced, ~50K writes/sec
3. Use Async for testing: Maximum speed, ~100K writes/sec
4. Checkpoint regularly: Prevent unbounded WAL growth
5. Flush before shutdown: Ensure all data is persisted

API Reference

StorageEngine Methods

is_wal_enabled() -> bool
wal_lsn() -> Option<u64>
flush_wal() -> Result<()>
replay_wal() -> Result<usize>
truncate_wal(up_to_lsn: u64) -> Result<()>
wal_sync_mode() -> Option<WalSyncMode>
set_wal_sync_mode(mode: WalSyncMode) -> Result<()>

WriteAheadLog Methods

open(db: Arc<DB>, sync_mode: WalSyncMode) -> Result<Self>
append(operation: WalOperation) -> Result<u64>
flush() -> Result<()>
replay() -> Result<Vec<WalEntry>>
truncate(up_to_lsn: u64) -> Result<()>
current_lsn() -> u64
set_sync_mode(mode: WalSyncMode)

Files

• Implementation: /home/claude/HeliosDB Nano/src/storage/wal.rs
• Integration: /home/claude/HeliosDB Nano/src/storage/engine.rs
• Configuration: /home/claude/HeliosDB Nano/src/config.rs
• Full Docs: /home/claude/HeliosDB Nano/docs/implementation/WAL_IMPLEMENTATION.md