WAL Quick Reference Guide

Configuration

Enable WAL

config.toml

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

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb --config config.toml

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
group_commit	Batched	~50K ops/s	1-2ms	High	High-throughput

Figures from internal tests (HeliosDB Lite, single-node write path); reproduce on your own hardware.

Common Operations

Write Operations (Automatic WAL Logging)

Every INSERT, UPDATE and DELETE is written to the WAL before it is applied. No application changes are needed.

Checkpoint

-- Flush the WAL
CHECKPOINT;

-- Flush the WAL and the storage backend
CHECKPOINT FORCE;

CHECKPOINT needs a role with maintenance privileges (for example postgres).

Crash Recovery

Recovery is automatic: when the server starts on a data directory, it replays the WAL before it accepts connections.

Graceful Shutdown

Stop the server cleanly with Ctrl+C, systemctl stop, or heliosdb-lite stop for a daemon, rather than killing the process. With async mode, writes acknowledged shortly before an unclean stop can be lost.

Best Practices

1. Production: wal_sync_mode = "sync" (or "group_commit" when you can accept a short batching window)
2. Periodic checkpointing: run CHECKPOINT from your scheduler during quiet periods
3. Monitor WAL size: the detailed /health check reports the WAL size and flags it above HELIOSDB_WAL_MAX_BYTES (default 1 GiB); see the Production Deployment Guide
4. Development/testing: wal_sync_mode = "async"

Troubleshooting

WAL not enabled

Check that wal_enabled = true is in the [storage] section and that the server was started with --config pointing at that file.

High write latency

Switch from sync to group_commit, or move the data directory to faster storage.

Large WAL size

Run CHECKPOINT, and check the WAL size in the detailed /health output.

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. Stop the server cleanly: Ensure all data is persisted