vibed/nbd/.nbd/tickets/833807.md

+++ title = "SQLite cache for list performance" priority = 3 status = "todo" ticket_type = "feature" dependencies = [] +++ Add an optional SQLite cache in .nbd/cache.db to accelerate nbd list and nbd ready for large ticket stores.

Motivation

list_tickets currently does O(n) file reads on every call. For stores with hundreds of tickets this is measurably slow. A SQLite cache avoids re-reading unchanged files by comparing file modification times (mtimes).

Approach

Crate dependency

Add sqlx with the sqlite and runtime-async-std features to Cargo.toml.

store.rs additions

New async function open_cache(root: &Path) -> Result<sqlx::SqlitePool>:

• Opens (or creates) .nbd/cache.db.
• Runs a migration: CREATE TABLE IF NOT EXISTS tickets (id TEXT PRIMARY KEY, json TEXT NOT NULL, mtime INTEGER NOT NULL).

New function list_tickets_cached(root: &Path) -> Result<Vec<Ticket>>:

1. Open cache.
2. Read directory listing to get file names and mtimes.
3. For each file: if the DB has a row with matching mtime, use cached JSON; otherwise read file, parse, insert/update row.
4. Delete DB rows for IDs no longer on disk.
5. Return deserialized tickets sorted by priority desc.

Keep existing list_tickets as the non-cached fallback. Consider making cmd_list and cmd_ready use list_tickets_cached when available.

Migration strategy

• The cache is always optional. If cache.db can't be opened, fall back to list_tickets (log a warning to stderr).
• The cache is never the source of truth — the JSON files are. The cache is always reconstructable by deleting .nbd/cache.db.

Decision point

Decide whether to enable the cache unconditionally or gate it behind a flag (--cache / NBD_CACHE=1). Recommendation: enable by default once the feature is stable.

Tests

• Unit test: cache hit returns same data as direct file read.
• Unit test: cache miss (mtime changed) re-reads the file.
• Unit test: deleted ticket is evicted from cache.
• Performance test (optional): benchmark 1000-ticket list with and without cache.

Files touched

• Cargo.toml — add sqlx
• src/store.rs — open_cache, list_tickets_cached
• src/tests.rs — cache unit tests
• docs/ARCHITECTURE.md — document the cache layer