Cache policy and invalidation

CacheDB uses Redis as a cache-aside result cache. A policy decides which reads are eligible, how long they remain useful, and which writes invalidate related cached results. The source database remains authoritative; cache policy is therefore part of normal operational change control.

Observe before reusing results

Start new workloads in transparent mode. CacheDB continues to parse statements, capture metrics, and expose query relationships while result lookup and storage are disabled. This provides the evidence needed to choose a policy without changing application behavior.

Full mode enables result reuse only for eligible reads. A write and a concurrent read can have a narrow window before related invalidation completes, so CacheDB provides eventual consistency, not a blanket strong-consistency guarantee.

Make the policy explicit

Rhai hooks let operators control SQL preparation, cache eligibility, TTLs, and post-write or post-DDL invalidation. A small policy can keep volatile reads out of the cache and apply a longer TTL to stable by-ID reads:

fn on_dql_parsed(ctx, metadata) {
    if metadata.tables.contains("users") {
        proxy::set_cache_ttl(3600);
    }
}

The production policy can also bypass a cache, skip a cache read for a controlled refresh, or skip a cache write. CacheDB ignores cache policy for explicit transactions, transparent mode, and statements that are not cacheable.

Invalidate conservatively

The default safety boundary for a completed write is the set of directly written tables. Relationships inferred from joins, predicates, subqueries, ranges, or ambiguous parameters may be incomplete. Where that is true, invalidate the written-table scope rather than assuming a narrow selective invalidation is safe.

Batch invalidation is the preferred pattern when several written tables are involved: it reduces Redis round trips and narrows the invalidation window. Its exact outcome remains workload-dependent and should be measured in the target environment.

Review, validate, and roll back

Treat a policy like application code. CacheDB supports policy validation and simulation before activation, synchronisation across proxy instances, runtime error visibility, and rollback of a previous published script. Review changes against realistic query shapes, consistency constraints, and representative write paths before moving a workload to full mode.

The AI Assistant can help investigate policy opportunities, but it does not replace human review or activate a policy by itself.

To assess cache eligibility and invalidation risks in your workload, request a cache-policy review.