How does the Dameon use SQLite WAL?

>Tech>Issue: SQL Busy>How does the Dameon use SQLite WAL?

Gabo H Beaumont

25 May 2026, 10:30

ContentPeopleCommentsCitations18

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.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime