Skip to content

CONCEPT Cited by 1 source

Lakebase Local File Cache (LFC)

The Local File Cache (LFC) is a Lakebase-specific caching layer on the compute-VM side of Lakebase that holds Postgres pages locally, softening the latency penalty of fetching pages from Pageserver across the storage-compute separation boundary.

The 2026-05-20 marketing-campaigns post is the first wiki source to disclose LFC by name, alongside the PREFETCH statistic. Verbatim:

"PREFETCH and FILECACHE are specific to Lakebase and show, respectively, how many prefetch requests were issued/hit/wasted and what were the hits/misses against the Local File Cache (LFC)."

Why LFC matters: the storage-compute-separation tax

In compute-storage- separated Postgres, the page cache (shared_buffers) is no longer the only thing standing between a query and disk. Pages that miss shared_buffers go to Pageserver — over the network — instead of to local disk. Without an intermediate cache, every miss pays a network round-trip; this would make hot working sets that overflow shared_buffers significantly slower than on a coupled-storage Postgres.

LFC is the answer: a compute-VM-local cache of Pageserver pages sized larger than shared_buffers, so:

  • shared_buffers hit → in-memory page (fastest)
  • shared_buffers miss + LFC hit → local-disk page (still much faster than network)
  • LFC miss → Pageserver fetch (slowest)

The cache hierarchy preserves locality-of-reference performance even when the working set exceeds RAM. The Pageserver round-trip cost only shows up for genuinely cold or rarely-accessed data.

The two metrics: PREFETCH and FILECACHE

Both are exposed alongside standard pg_stat_statements-style query statistics in the Lakebase SQL console UI:

Metric Counts Meaning
PREFETCH Prefetch requests issued / hit / wasted How effectively Lakebase predicts pages it'll need before a query asks for them
FILECACHE LFC hits / misses Working-set fit against the local file cache layer

A high PREFETCH "wasted" rate suggests Lakebase is fetching pages a query never used — overhead. A high FILECACHE miss rate suggests the working set exceeds LFC capacity — every miss is paying the full Pageserver round-trip cost.

These metrics are the load-bearing observability layer for diagnosing query performance problems that come from storage-compute-separation behaviour (vs problems that come from query plan, locking, or application-side issues).

What's not disclosed

The 2026-05-20 post discloses only the metric names and what they count. Several internal mechanics remain undisclosed in the wiki:

  • Cache structure and eviction policy. Probably LRU-like, but not confirmed.
  • Sizing. Whether LFC scales with compute size, is a fixed fraction of compute, or has independent configuration is not documented.
  • Pre-warming. Whether LFC survives compute scale-down (or even compute restart) is not addressed. The earlier Lakebase cache-prewarming-for-zero-downtime-patching framing (systems/lakebase page) suggests warm-state is preserved across at least some compute-lifecycle events, but the LFC specifically is not named in that context.
  • Coherence. How LFC coherence is maintained when Pageserver pages change underneath (e.g. via WAL apply on Pageserver side) is not described.
  • Prefetch heuristics. What signals drive prefetch predictions — sequential scan detection, query-plan-driven prefetch, or something else — is not disclosed.

Implications for query tuning

The 2026-05-20 post implicitly frames LFC observability as part of the standard Postgres tuning loop:

  1. Identify slow queries via pg_stat_statements (standard Postgres) or the Lakebase UI.
  2. Inspect PREFETCH and FILECACHE for storage-compute- separation-specific issues:
  3. High FILECACHE miss → working set too large; consider work_mem bump (post recommends 256 MB on larger compute) or larger compute sizing.
  4. High PREFETCH wasted → query plan may benefit from different access path or index.
  5. Apply standard Postgres remediation (index, query rewrite, partition, vacuum tuning) before considering Lakebase- specific knobs.

LFC is the Lakebase-specific layer that introduces a new diagnostic question relative to vanilla Postgres tuning: "Is this slow because of the storage-compute boundary, or because of standard Postgres reasons?" PREFETCH and FILECACHE are how you answer it.

Seen in

Last updated · 542 distilled / 1,571 read