---
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"
```

```bash
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

```sql
-- 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](/docs/lite/guides/production_deployment/#monitoring)
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