# Caching & freshness

What the result cache does, and how it becomes fresh again.

HTML: https://igloodb.github.io/docs/caching/
Source: https://github.com/igloodb/igloodb/blob/163320482d98bc3d6c49eb85acb0f511461a8284/src/cache_layer.rs (reviewed revision 1633204)

## 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.

```toml
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.

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

> This is a local invalidation mechanism. Igloo does not yet subscribe to PostgreSQL WAL or ingest a real CDC stream. Source updates alone do not invalidate a cached result; freshness depends on new event files or TTL expiry.

## 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.