Caching

StorageCacheNo Stale Reads

Stable On by default · production-ready

What it is

AetheriusDB’s cache is part of the query engine itself, not a separate key-value store you run alongside it. You never stand up a Redis or Memcached, and you never debug a cache that has drifted out of sync with the database.

There are two integrated behaviors:

• Read-through — the first query to touch warmer or colder data promotes it into memory; later queries enjoy memory-speed access.
• Write-through — a write becomes durable and visible in the same committed step, so readers see the latest state at the moment the writer is told the commit succeeded.

Why it matters

Bolt-on caches introduce a second consistency model and a second source of operational truth. Every cache-aside read in the application is a potential race window. A cache that lives inside the engine removes that whole category of bug and the operational surface that comes with it.

• No cache-aside pattern — the application talks to one database, period.
• No de-sync — writes that complete are visible to subsequent reads, by construction.
• Access-aware eviction — eviction is driven by how hot data actually is, so a one-time scan does not blow away your hot keys.

How you use it

You do not configure cache keys — the cache operates on the same data the storage engine already holds. You can inspect hit ratios, override promotion on specific tables, and tune how often buffered writes are flushed.

-- Inspect the hit ratio for each table over the recent window.
SELECT table_name,
       reads_hot,
       reads_promoted,
       round(reads_hot * 100.0 / (reads_hot + reads_promoted), 1) AS hit_pct
  FROM aetherius_system.cache_stats
 ORDER BY hit_pct DESC;

-- Disable promotion for a scan-once batch table — keep the cache
-- focused on the interactive tables.
ALTER TABLE nightly_load
  SET promote_on_read = FALSE;

-- Force buffered writes for a table to flush to durable storage now.
FLUSH TABLE ingestion_events;

With promote_on_read = FALSE, your nightly batch still reads correctly from cold storage — it just will not push hot tables out of memory while doing so.

Illustrative syntax

The cache_stats columns and the promote_on_read / FLUSH TABLE spelling shown here illustrate the feature shape; confirm the exact grammar against your server version.

Notes & caveats

Tip

Watch the cache-stats view weekly. If a critical table shows a low hit ratio under steady-state load, that is the signal to pin its hot slice or raise the residency budget for its tier. The cache is transparent — these diagnostics are how you steer it.

Large scans can warm bytes you don’t want hot

An analytical scan that touches an entire table can warm a lot of data you do not actually want resident. For known-cold reporting jobs, set promote_on_read = FALSE on the target tables so the cache stays focused on your interactive traffic.

Multi-Tier Residency →

The tiering that read-through and eviction operate over.

Pinned Tables →

When the cache alone isn't enough — pin the bytes that cannot leave memory.

Memory Compaction →

Keeps resident memory contiguous as writes and evictions churn.

Crash Recovery & Durability →

How write-through durability survives a power loss.