We are not using it in a special way. We are using it as SQLite.

The daemon uses SQLite WAL in three places/concepts.

Opens SQLite in WAL mode

In backend/storage/sqlite.go, OpenSQLite runs:

"PRAGMA journal_mode = WAL;",

So the DB uses:

db.sqlite       main DB
db.sqlite-wal   write-ahead log
db.sqlite-shm   WAL coordination/shared-memory file

Also, the pool opens connections with SQLITE_OPEN_WAL by default in backend/util/sqlite/sqlitex/pool.go.

Raises SQLite auto-checkpoint threshold

Current code sets:

PRAGMA wal_autocheckpoint = 10000;

This means SQLite should not automatically checkpoint on foreground commits until the WAL reaches a much larger threshold.

Why? Because auto-checkpoint can make an unlucky foreground writer pay checkpoint cost during COMMIT, causing long write holds.

Runs a background checkpoint goroutine

Current code starts:

sqlitex.StartWALCheckpointer(pool, walCheckpointInterval, ...)

with:

walCheckpointInterval = 5 * time.Second

That background task periodically runs roughly:

PRAGMA wal_checkpoint(PASSIVE);

The intent:

foreground writes append to WAL quickly

background checkpoint copies WAL frames into db.sqlite

foreground commits avoid paying big checkpoint/fsync costs

checkpoint is PASSIVE, so it should not block active readers/writers

Why WAL helps

WAL lets the daemon have:

many readers + one writer

instead of readers and writers blocking each other more often.

So reads like feed/list/document queries can usually run while a writer appends to WAL.

What WAL does not solve

WAL still allows only:

one writer at a time

So these still contend:

PutMany
connect peer update
DomainStore update
sync/loadStore

They all fight for the single SQLite writer slot.

Important detail from your machine

After closing the app, your files still show:

db.sqlite-wal 648 MB

That suggests the daemon is either:

not truncating the WAL on shutdown

not fully checkpointing

or checkpointed frames are reusable but the physical file remains large

Current background checkpoint uses PASSIVE, which checkpoints frames but normally does not guarantee truncating the WAL file size to zero.

Summary

The daemon uses WAL to improve read/write coexistence and avoid foreground checkpoint stalls, but WAL is not a fix for writer contention. It helps reads; it does not allow parallel writes.