Speed up the SQLite metadata-cache build (connection reuse + synchronous=NORMAL)

[cboos]

Part of #248.

Problem

Building the SQLite metadata cache dominates per-project processing.
Instrumenting a real (contention-immune) build showed the cost is
connection churn, not fsync: every CacheManager method (reads
included) opened its own sqlite3.connect + PRAGMAs — ~189 connection
opens per single-project build (~3.9ms each), against only 47 commits.
(An earlier "fsync is the bottleneck" reading turned out to be a
measurement artifact from toggling use_cache under load.)

Change

• PRAGMA synchronous=NORMAL on cache connections (WAL). The cache
  is regenerable, so the durability trade-off — only an OS/power crash
  can lose the last commit, not an app crash — is appropriate.
• CacheManager.batch() — an opt-in context that reuses one
  connection for the duration of a build instead of opening ~189. The
  converter wraps each per-project build in it. Outside a batch,
  behaviour is byte-for-byte unchanged (open-per-call), preserving the
  Windows file-lock semantics the per-call design relied on.
• The converter changes are a pure reindent (control flow preserved;
  nullcontext keeps the no-cache path identical; nested batches are a
  no-op reuse).

Why the open-per-call default is preserved

A persistent connection holds .db/.db-wal/.db-shm open, which on
Windows breaks TemporaryDirectory cleanup and clear_cache rmtree
(WinError 32). batch() therefore closes the shared connection at
scope end (and on exception) before any teardown can run. This is
pinned by tests in test_cache_sqlite_integrity.py, not just asserted:

• reuse within a batch; nested batch is a no-op reuse; only the outermost
  closes
• the shared connection is closed even if the build raises (no stale
  connection leaks the lock)
• rmtree-after-batch succeeds on Windows
• the default path opens a fresh connection per call

Results (local Windows)

• connection opens: 189 → 14 (93%) for a single-project build
• clean sample convert (min-of-6): 5.44s → 4.10s (~25%)

Cache invalidation (mtime), schema-version rebuild, and concurrent-reader
safety are unchanged and covered by the integrity tests and the existing
cache suite. The connection model is documented in
dev-docs/application_model.md.

Unlike the test-only companions in #248, this is a change to production
code that speeds up real cache builds on every platform (Windows most,
since connection/file overhead is heaviest there).

Summary by CodeRabbit

• New Features

  • Added batched cache operations for faster work across larger cache-building flows.
  • Improved connection handling so repeated cache actions can reuse one shared database connection within a batch.

• Bug Fixes

  • Reduced the risk of leftover database locks after cache updates.
  • Ensured cache connections are closed reliably, even when errors occur.
  • Kept cache settings consistent for better SQLite stability and durability.

• Tests

  • Added coverage for connection reuse, cleanup behavior, nested batches, and persisted writes.

[coderabbitai]

Warning

Review limit reached

@cboos, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 17 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 26f4d5b8-1b84-46ff-bf8c-b9c637fdc916

📥 Commits

Reviewing files that changed from the base of the PR and between d487181 and 51adead.

📒 Files selected for processing (2)

• claude_code_log/cache.py
• test/test_cache_sqlite_integrity.py

📝 Walkthrough

Walkthrough

CacheManager gains a batch() context manager that opens one SQLite connection and reuses it across nested _get_connection() calls, with guaranteed cleanup on exit. Three converter hotspots (load_directory_transcripts, ensure_fresh_cache, _generate_individual_session_files) are wrapped in this context. Tests validate lifecycle semantics and a synchronous=NORMAL pragma; docs describe the connection model.

Batched SQLite Connection Reuse

Layer / File(s)	Summary
_configure_connection, _get_connection, and batch() implementation claude_code_log/cache.py	Adds _shared_conn field; extracts _configure_connection() for WAL/pragma setup; updates _get_connection() to yield the shared connection when inside a batch; adds batch() context manager with nesting no-op and guaranteed teardown.
Integration into converter hotspots claude_code_log/converter.py	Wraps the per-file loop in load_directory_transcripts, the invalidation+repopulation sequence in ensure_fresh_cache, and the per-session loop in _generate_individual_session_files each in cache_manager.batch() (falling back to contextlib.nullcontext() when no cache manager is present).
Tests and documentation test/test_cache_sqlite_integrity.py, dev-docs/application_model.md	Adds test_synchronous_normal PRAGMA assertion, a TestBatchConnectionReuse suite covering connection reuse, cleanup on normal/exceptional exit, write persistence, and Windows file-lock release; documents the connection model in application_model.md.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 One connection to rule them all,
No more open-close with every call!
I batch my hops across the field,
WAL mode keeps my writes well-sealed.
The shared conn clears when batch is done—
A tidy burrow, leaks: zero, none!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main optimization: faster SQLite cache builds via connection reuse and synchronous=NORMAL.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev/cache-sqlite-batching

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@claude_code_log/cache.py`:
- Around line 346-347: The SQLite connection setup in `_get_connection()` and
the `batch()` path opens a handle before calling `_configure_connection()`, but
if configuration fails the connection is left open and can lock the DB/WAL
files. Update the setup flow around `sqlite3.connect()` and
`_configure_connection()` to use a close-on-failure path so any exception during
initialization closes the connection before re-raising.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7faf2dbd-9d8e-457c-85f0-574aeffac017

📥 Commits

Reviewing files that changed from the base of the PR and between 4bd633f and d487181.

📒 Files selected for processing (4)

• claude_code_log/cache.py
• claude_code_log/converter.py
• dev-docs/application_model.md
• test/test_cache_sqlite_integrity.py