Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[fleet-standing harvest] WAL grows unbounded (2.9 GiB) — pooled readonly connections never end their read transaction

Open
  • Is something wrong?
#670 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Quiet
Tech stack
python, sqlite
Domain
backend, database

Research direction

Start in src/brainlayer/mcp/_shared.py, where the fixed-size readonly WAL VectorStore pool is defined, and read AGENTS.md:41-43 for the recorded WAL concern. Verify that pooled readers end transactions between checkouts or are recycled, then add the required alarm when the WAL ceiling is crossed; confirm the behavior against the WAL growth and recovery concerns described here.

Written by the indexing model from the issue text.

Description

WAL: 3.14 GB confirmed, and the mechanism is UNBOUNDED GROWTH, not a stuck checkpoint. Measured read-only (?mode=ro), prod untouched:

brainlayer.db      16 G
brainlayer.db-wal  3,138,747,872 bytes (2.9 GiB)
brainlayer.db-shm  5.8 M
journal_mode=wal   wal_autocheckpoint=1000   busy_timeout=5000
BrainBarDaemon pid 21818  started Mon Aug 3 03:22:20  ELAPSED 18:18:29   (fd 6u = READ-WRITE)
Python         pid 21819  same start, 35 open fds on brainlayer.db

Correction to the framing: autocheckpoint is NOT disabled and checkpoints are NOT failing to run. A WAL checkpoint can copy pages into the DB, but it cannot reset or truncate the WAL past the oldest live reader's snapshot. So every checkpoint runs, partially succeeds, and cannot reclaim a byte while a reader holds an 18-hour-old snapshot. That is why it grows without bound rather than plateauing — this will not self-heal, and it has no ceiling short of the disk.

The reader is our own MCP read pool. src/brainlayer/mcp/_shared.py keeps a fixed-size readonly WAL VectorStore pool (BRAINLAYER_READ_POOL_SIZE, default 8, 4 on M1). A pooled connection only pins a snapshot while a read transaction is open, so the defect is that pooled readers hold an open read transaction across their idle life instead of ending it between checkouts.

REAL FIX: pooled readonly connections must end their read transaction between checkouts — and/or the pool must recycle connections on a max-age / max-query basis so no snapshot can ever be 18 hours old.

Required as part of the fix (orc ruling, line 12781): a WAL size ceiling that ALARMS (not deletes) when crossed. Note AGENTS.md:41-43 already records "WAL can grow to 4.7GB" as a known issue — noticing was recorded as sufficient. The alarm is the fix for that too.

Why it matters beyond disk: a 2.9 GiB WAL is replayed on crash recovery, so an unclean shutdown means a very long, very IO-heavy restart on a 16 GB DB.

Archive reference: collab/archive/FLEET-STANDING-archive-2026-08-08.md line 12732

— EtanHey's maintenanceClaude (lead) · claude-code/claude-fable-5

Dominant language
Python
Stars
9
Forks
7
Avg merge
2h 8m
Merged PRs (30d)
225

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from EtanHey/brainlayer

All issues in EtanHey/brainlayer

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.