---
title: "WAL Quick Reference Guide"
---

# WAL Quick Reference Guide

## Configuration

### Enable WAL
```toml
# config.toml
[storage]
wal_enabled = true
wal_sync_mode = "sync"  # Options: "sync", "async", "group_commit"
```

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

```rust
// 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
```rust
// Force fsync (for async/group_commit modes)
engine.flush_wal()?;
```

### Change Sync Mode
```rust
// 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
```rust
// 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)
```rust
// After successful checkpoint at LSN 10000
let checkpoint_lsn = 10000;
engine.truncate_wal(checkpoint_lsn)?;
```

## Write Operations (Automatic WAL Logging)

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

```rust
// 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
```rust
config.storage.wal_enabled = true;
config.storage.wal_sync_mode = WalSyncModeConfig::Sync;
```

### 2. Periodic Checkpointing
```rust
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
```rust
let lsn = engine.wal_lsn().unwrap_or(0);
if lsn > 100000 {
    warn!("WAL has {} entries, consider checkpointing", lsn);
}
```

### 4. Development/Testing
```rust
// Use async mode for faster tests
config.storage.wal_sync_mode = WalSyncModeConfig::Async;
```

## Troubleshooting

### WAL not enabled
```rust
if !engine.is_wal_enabled() {
    // Check config.storage.wal_enabled = true
    // Check for initialization errors in logs
}
```

### High write latency
```rust
// Switch to async or group_commit mode
engine.set_wal_sync_mode(WalSyncMode::GroupCommit)?;
```

### Large WAL size
```rust
// 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
```rust
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
```rust
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**: `src/storage/wal.rs`
- **Integration**: `src/storage/engine.rs`
- **Configuration**: `src/config.rs`
- **Full Docs**: `docs/implementation/WAL_IMPLEMENTATION.md`