Caching & freshness

Arrow-native results#

The cache stores the actual Arrow RecordBatch values produced by a query. It is shared through Arc<Cache> and protected by a mutex. It tracks hits, misses, LRU evictions, TTL evictions, and entry count through stats().

serve caches eligible SELECT / WITH statements without parameters. Parameterized statements bypass the cache so different bindings cannot share a result. The cache is process-local and is lost on restart.

SQL keys#

Keys are derived from a PostgreSQL-dialect parse and display round-trip, with quote-aware lexical normalization as a fallback. Whitespace, SQL keyword case, and trailing semicolons can normalize to the same key. String literal contents remain significant.

This is SQL text normalization, rather than logical-plan fingerprinting. Semantically equivalent queries are not guaranteed to share a cache entry.

LRU and TTL#

The default capacity is 1,024 entries and the default TTL is 300 seconds. Both are configurable and must be positive. A new entry beyond capacity evicts the least recently used entry. Expired entries miss on access and are removed.

The limit counts entries rather than bytes. It is not a memory budget: one large result may consume significant memory.

cache_max_entries = 1024
cache_ttl_seconds = 300
cdc_poll_seconds = 10

File-based change events#

In serve mode, a background task polls cdc_path. It reads newly discovered .json files and clears the entire result cache if any new event is found. Files are deduplicated by path for the lifetime of the listener.

Event contents do not currently identify affected tables or drive row-level updates. Use a new filename for each event; rewriting a previously seen file does not create a new event.

printf '%s\n' '{"event":"update"}' > local_cdc/event-002.json

Planned improvements#

The roadmap includes logical replication, dependency-aware invalidation, plan-based cache keys, a byte budget, persistent backends, and observable freshness policies. These are not available in the current implementation.