fix(sqlite-native): gate native read cache behind env var

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630 👈 (View in Graphite)
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: fix(sqlite-native): gate native read cache behind env var

Summary: This PR gates the native SQLite VFS read cache behind the RIVETKIT_SQLITE_NATIVE_READ_CACHE env var (disabled by default) to align native behavior with the WASM VFS, which has no read cache.

---

Code Quality

read_cache_enabled() initialization (vfs.rs:106): Using a function-level static OnceLock is idiomatic and correct. The env var is read exactly once per process life and cached. Worth noting in a comment that this is intentionally process-scoped -- subsequent setenv calls after first initialization have no effect.

Option pattern (vfs.rs:296): Clean representation. read_cache_enabled.then(HashMap::new) is idiomatic Rust.

VfsContext.read_cache_enabled field (vfs.rs:155): Good decision to snapshot the flag at VFS creation rather than calling read_cache_enabled() per file open. Consistent across file handles opened through the same VFS instance.

---

Minor Issue

Unnecessary allocation in batch flush (vfs.rs:920):

When read_cache is None, the dirty buffer is still collected into a Vec and then immediately dropped. Not a correctness issue (std::mem::take correctly clears the dirty buffer regardless), but it allocates on every atomic commit when caching is disabled. Suggested fix -- take the BTreeMap directly and skip the Vec:

let dirty = std::mem::take(&mut state.dirty_buffer);
if let Some(read_cache) = state.read_cache.as_mut() {
    for (chunk_index, data) in dirty {
        let key = kv::get_chunk_key(file.file_tag, chunk_index);
        read_cache.insert(key.to_vec(), data);
    }
}
// dirty is dropped here if read_cache is None, no Vec allocation

---

Test Coverage

No tests for the env var gating. Given that OnceLock makes env-var-based flags hard to test in parallel suites, this is understandable. A doc comment on read_cache_enabled() noting that it reads once at first call and subsequent env var changes are ignored would prevent future confusion.

---

Documentation

The env var RIVETKIT_SQLITE_NATIVE_READ_CACHE is undocumented outside the code. If this is user-facing (operators tuning performance), it should appear in the self-hosting configuration docs. If developer-only, the code comment is sufficient.

---

Correctness

The change is correct. All cache interactions are properly guarded, and the no-cache path does not regress writes (data still goes through KV; the cache was purely an optimization). The WASM parity goal is achieved by defaulting the cache to disabled.

---

Overall: Solid, focused change. The one actionable suggestion is removing the unnecessary Vec collect in the flush path by taking the BTreeMap directly. Everything else is clean and idiomatic.

Generated with Claude Code