What is the Redis cache-aside pattern, and why use it in a monolith?

In the Redis cache-aside pattern, the application owns both the read path and the write path, and Redis holds copies of selected query results. On a read, the code checks Redis first. On a miss, it queries the database, stores the result in Redis, and returns it. On a write, the code updates the database and then invalidates or overwrites the cached entry. Redis never talks to the database, and the database never knows Redis exists. All coordination lives in your application code. That is the trade-off: you get full control, and you take full responsibility for keeping the copies correct.

This fits a monolith well for three reasons:

  • One codebase sees every read and write. Invalidation is hard when many services write to the same tables. In a monolith, you can find every code path that mutates a given entity and attach invalidation to it.
  • No new service to run. You add a Redis instance and a client library. You do not add a caching proxy or a sidecar, and you do not move data ownership elsewhere.
  • It relieves a single primary database. Monoliths usually sit on one primary. A handful of repeated, expensive reads can consume a large share of its capacity.

The approach in this tutorial is deliberately narrow. You will wrap a few hot queries that you have measured, each with its own key design, TTL, and invalidation rule. It is not a generic query cache that intercepts everything. The tutorial is for backend and platform engineers whose database is under read pressure from a small set of repeated, costly queries.

Which queries should you cache, and when should you avoid caching?

Start from evidence, not intuition. Pull per-statement statistics from the database: the slow query log, pg_stat_statements in PostgreSQL, or the statement digest tables in MySQL's Performance Schema. Join them with application traces so each normalized query maps to the endpoints that issue it. Rank by call count × mean latency. A 4 ms query called thousands of times a minute can consume more total database time than a multi-second report that runs hourly. Then score each candidate by how stale its result can be before someone notices or is harmed. Your shortlist is the queries with high total cost and tolerant staleness.

Caching everything is a mistake for four reasons:

  • Key cardinality can grow without limit. Keys built from user IDs, free-text filters or pagination offsets multiply quickly.
  • Invalidation surface grows. Every cached query is another write path that must evict correctly as the schema evolves.
  • Debugging gets harder. A wrong answer now has two possible sources.
  • Cheap queries gain almost nothing. For an indexed primary-key lookup, a Redis round trip plus serialization can cost about as much as the query itself.

Exclude reads where staleness breaks correctness, or handle them specially. These include account balances, inventory counts, authorization checks, and any read that needs read-your-writes.

Query trait Verdict
Frequent, expensive, tolerates seconds–minutes of staleness Cache
Cheap indexed lookup Don't cache
Unbounded parameter space (search, deep pagination) Don't cache
Balances, inventory, permissions Don't cache, or use short TTL plus authoritative recheck on writes
User must see own write immediately Needs extra handling: bypass or evict on write

How does the cache-aside read path work?

The read path has four steps, and each one affects correctness:

  1. Build a deterministic key. Derive it from a named query identity and its parameters, such as app:v1:user_orders:{user_id}:{page}, not from the SQL text.
  2. GET the key. On a hit, deserialize the value and return it. The database is never touched.
  3. On a miss, run the query and serialize the result.
  4. Store it with SET key value EX seconds and return. This writes the value and its expiry in one command. If you call SET and then EXPIRE separately and the process dies between them, the key never expires.
HIT:    App --GET--> Redis --value--> App

MISS:   App --GET--> Redis --nil--> App
        App --SELECT--> DB --rows--> App
        App --SET key val EX ttl--> Redis
        App --> caller

WRITE:  App --UPDATE--> DB
        App --DEL key--> Redis   (next read repopulates)

Key design. Namespace keys by application and query name so you can find, scan and invalidate them by prefix. Hashing raw SQL strings is fragile: whitespace, parameter order or an ORM upgrade produces a new hash for the same logical query, and invalidation code can't easily recompute it. Include every scoping parameter, such as tenant, user and locale. If one is missing, two callers resolve to the same key, and one user is served another user's data.

Versioning and serialization. The v1 segment stores a schema version. During a rolling deploy, old and new code run at the same time. If the result shape changes, bump the version so each build reads only entries it wrote. JSON is easy to debug and tolerates added fields. A binary format such as MessagePack or Protobuf saves memory and CPU, but you then need to manage schema evolution explicitly.

     +-------+            +-------+            +-------+
     |  App  |            | Redis |            |  DB   |
     +---+---+            +---+---+            +---+---+
         |                    |                    |
 HIT     |--GET key---------->|                    |
         |<--------value------|                    |  deserialize, return
         |                    |                    |  (DB not touched)
         |                    |                    |
 MISS    |--GET key---------->|                    |
         |<----------nil------|                    |
         |--SELECT ...---------------------------->|
         |<---------------------------------rows---|  serialize result
         |--SET key EX ttl--->|                    |  value + TTL, 1 cmd
         |                    |                    |  return to caller
         |                    |                    |
 WRITE   |--UPDATE ...---------------------------->|
         |<------------------------------------ok--|
         |--DEL key---------->|                    |  next read misses
         |                    |                    |  and repopulates
         |                    |                    |

  app:v1:user_orders:{user_id}:{page}
  |   |  |           |         +-- page parameter
  |   |  |           +-- user scope (omit it = data leak)
  |   |  +-- named query identity, not a SQL hash
  |   +-- schema version: bump when result shape changes
  +-- app namespace: scan and invalidate by prefix

Cache-aside hit, miss and write paths between the app, Redis and the database. A miss stores the value and its TTL in a single SET ... EX command, and the key's segments carry the namespace, schema version, query identity and every scoping parameter.

How do you implement cache-aside with invalidation and a TTL strategy?

The read path, in language-neutral pseudocode:

  1. key = build_key(version, entity, params)
  2. value = cache.get(key). Treat a timeout or error as a miss.
  3. On a hit, return deserialize(value).
  4. On a miss, row = db.query(...), then cache.set(key, serialize(row), ttl), then return row.

The example that follows uses redis-py with socket_timeout set to tens of milliseconds. A slow Redis then falls back to the database instead of stalling the request. The key builder prepends a version prefix such as v3:. Bumping it after a schema change orphans old entries, and their TTLs remove them.

On writes, delete the key in an after-commit hook. If you delete before commit, a reader can cache the old row. If you update the value in place, two concurrent writers can leave the losing writer's value behind.

Delete-on-write still has a race. A reader misses and reads the old row. The writer then commits and deletes the key, and the reader sets the stale value after that delete. Delayed double-delete, a second delete about a second later, narrows this window. It fails if the reader stalls longer than the delay, so the TTL is the real backstop.

Set each TTL from the query's staleness tolerance and add random jitter (say ±10%) so keys don't expire together. Give hot keys short TTLs because they refill cheaply. Long-tail keys can live longer. Every key gets a TTL, even "permanent" ones, so missed invalidations heal themselves.

Cache "not found" results as a sentinel with a short TTL, such as 30 seconds. This stops repeated lookups of missing IDs from reaching the database. For large result sets, cache IDs or individual pages rather than the full result, or skip caching above a size limit. Large values tie up Redis's single command thread and add network transfer on every read.

import json, random, threading
import redis

# Short timeouts: a slow Redis becomes a cache miss, not a stalled request.
r = redis.Redis(host="cache.internal", port=6379,
                socket_timeout=0.05, socket_connect_timeout=0.05)
VERSION = "v3"            # bump after a schema change; old keys age out via TTL
MISSING = b"__none__"     # sentinel for negative caching

def build_key(entity, **params):
    parts = ":".join(f"{k}={params[k]}" for k in sorted(params))
    return f"{VERSION}:{entity}:{parts}"

def jittered(base_ttl):
    return int(base_ttl * random.uniform(0.9, 1.1))  # +/-10% spreads expiries

def cached_get(entity, loader, base_ttl, **params):
    key = build_key(entity, **params)
    try:
        raw = r.get(key)
    except redis.RedisError:
        return loader(**params)             # Redis down or slow: use the DB
    if raw is not None:
        return None if raw == MISSING else json.loads(raw)
    row = loader(**params)
    try:
        if row is None:
            r.set(key, MISSING, ex=30)      # short TTL for 'not found'
        else:
            r.set(key, json.dumps(row), ex=jittered(base_ttl))
    except redis.RedisError:
        pass                                # caching is best-effort
    return row

def safe_delete(key):
    try:
        r.delete(key)
    except redis.RedisError:
        pass                                # TTL remains the backstop

def update_price(db, product_id, price):
    with db.transaction():                  # placeholder: commits on clean exit
        db.execute("UPDATE products SET price = %s WHERE id = %s", (price, product_id))
    key = build_key("product", id=product_id)
    safe_delete(key)                        # delete only after commit
    threading.Timer(1.0, safe_delete, args=(key,)).start()  # delayed double-delete

A redis-py cache-aside helper with a versioned key builder, jittered TTLs, a negative-cache sentinel, and a database fallback on Redis errors, plus a write path that deletes the key after commit and again about a second later.

How do you prevent a cache stampede on hot keys?

When a hot key expires, every request that arrives before the first rebuild finishes sees a miss. If the key serves 500 requests per second and the query takes 200 ms, roughly 100 identical queries hit the database at once (illustrative estimate). This is a cache stampede, and it hits the query you most wanted to protect.

Per-key lock. On a miss, try SET lock:{key} <token> NX EX 5. The winner runs the query and writes the cache. Losers sleep briefly with jitter and re-read the cache. The winner releases the lock with a short Lua script that compares the token and then calls DEL. Because the script runs atomically, a holder whose lock already expired cannot delete a lock that another process now owns. Set the lock TTL longer than the slowest expected query. If the holder crashes, waiters stall until the lock expires.

In-process coalescing. Keep a map from key to in-flight future in each instance. Concurrent callers await the same future, so each instance sends at most one query per key. This needs no Redis round trip, but N instances can still send N queries.

Early refresh. Recompute before expiry. You can do this probabilistically, where the chance of refreshing rises as the TTL runs down, or with a background job for known hot keys. Readers never wait, but you pay for refreshes that may not be needed.

Approach Added latency on miss Complexity Failure mode
Per-key lock Waiters poll or back off Medium Crashed holder delays refresh until the lock TTL expires
In-process coalescing Waiters share one query Low One query per instance, not per cluster
Early refresh None for readers Medium–High Extra background database load
import json, random, time, uuid
import redis

r = redis.Redis(host="localhost", port=6379, decode_responses=True)

# Delete the lock only if it still holds our token. GET and DEL run atomically
# in Redis, so a holder whose lock expired cannot delete another owner's lock.
RELEASE = r.register_script("""
if redis.call('GET', KEYS[1]) == ARGV[1] then
  return redis.call('DEL', KEYS[1])
end
return 0
""")

def get_with_lock(key, load, ttl=300, lock_ttl=5, wait_budget=3.0):
    cached = r.get(key)
    if cached is not None:
        return json.loads(cached)
    lock_key = f"lock:{key}"
    token = uuid.uuid4().hex
    deadline = time.monotonic() + wait_budget
    while True:
        # SET NX EX: only one caller wins. lock_ttl must outlast the slowest query.
        if r.set(lock_key, token, nx=True, ex=lock_ttl):
            try:
                value = load()
                r.set(key, json.dumps(value), ex=ttl)
                return value
            finally:
                RELEASE(keys=[lock_key], args=[token])
        # Lost the race: back off with jitter, then re-check the cache.
        time.sleep(0.05 + random.uniform(0, 0.05))
        cached = r.get(key)
        if cached is not None:
            return json.loads(cached)
        if time.monotonic() > deadline:
            # Holder may have crashed; stop waiting and query directly.
            return load()

A per-key Redis lock taken with SET NX EX. Waiters back off with jitter. The lock is released by a Lua script that deletes it only if the caller's token still matches.

What happens when Redis fails, and how do you monitor and roll out the cache?

Treat Redis as optional on the read path

A cache read should fail fast. Set client timeouts in the low milliseconds, and on a timeout or connection error, fall back to the database. Do not retry against Redis. A slow cache is worse than no cache, because every request pays the timeout and then the query anyway.

The bigger risk is dependency. If the database can only handle current traffic because the hit ratio is high, then a Redis restart, failover or FLUSHALL becomes a database outage. Size the database for a cold cache. If you can't, put a circuit breaker or load shedding in front of the fallback path, so that during an outage you reject or degrade some requests instead of saturating the primary.

What to monitor

  • Hit ratio per key namespace. A global ratio hides one cold query family behind many warm ones.
  • Miss latency, which is cache lookup plus query plus write-back.
  • Database query rate for each cached query, before and after rollout.
  • Evictions and memory used against the maxmemory limit.

For a pure cache, set maxmemory and maxmemory-policy allkeys-lru (or allkeys-lfu if a stable hot set matters more than recency). The default, noeviction, makes writes fail once memory is full. The volatile-* policies evict only keys that have a TTL, so any key written without one can never be evicted.

Rolling out

Put each cached query behind its own feature flag. Start in shadow mode: serve the database result, read the cache alongside it, and log mismatches. Before you cut over critical keys, warm them with a rate-limited job so the warm-up does not become the load spike you are trying to avoid.

import json
import threading
from collections import Counter

import redis
from redis.backoff import NoBackoff
from redis.retry import Retry

# Fail fast: tight timeouts and zero retries, so a sick Redis costs ~50 ms, not seconds.
cache = redis.Redis(
    host="cache.internal", port=6379,
    socket_connect_timeout=0.05, socket_timeout=0.05,
    retry=Retry(NoBackoff(), 0),
)

stats = Counter()                               # export per-namespace hit/miss to your metrics system
db_fallback = threading.BoundedSemaphore(20)    # cap concurrent DB queries on the miss path

class Overloaded(Exception):
    """Raised to shed load instead of saturating the primary."""

def top_products(db, category_id):
    ns, key = "products:top", f"products:top:v1:{category_id}"
    try:
        cached = cache.get(key)
        if cached is not None:
            stats[f"{ns}:hit"] += 1
            return json.loads(cached)
    except redis.RedisError:
        stats[f"{ns}:error"] += 1              # treat as a miss; never retry Redis here
    stats[f"{ns}:miss"] += 1

    if not db_fallback.acquire(blocking=False):  # cold or down cache: reject, don't pile on
        raise Overloaded(ns)
    try:
        rows = db.fetch_top_products(category_id)
    finally:
        db_fallback.release()

    try:
        cache.set(key, json.dumps(rows), ex=300)  # write-back is best effort
    except redis.RedisError:
        pass
    return rows

A cache-aside read that fails fast on Redis errors with no retries, records hit, miss and error counts per key namespace, and sheds load with a bounded semaphore so a cold or unavailable cache cannot flood the database.

What are the alternatives to Redis cache-aside, and what does it cost to run?

Cache-aside is not always the cheapest fix. Rule out these options first:

Option Consistency Operational cost Best fit
Query and index tuning Strong Low Slow queries caused by bad plans or missing indexes
Read replicas Replication lag Medium: more database nodes Read-heavy load where slightly stale reads are acceptable
Materialized views or precomputed tables Stale until refresh Medium: refresh jobs Aggregates and reports
In-process cache Inconsistent across instances Low Small, rarely changing data such as config or feature flags
HTTP or response caching Stale until expiry Low to medium Public or per-user responses that can be shared
Redis cache-aside Stale up to the TTL or until invalidation Medium: Redis plus code paths Hot, repeated, expensive lookups by key

Development cost

Invalidation is cheap for single-row lookups. It gets expensive for list, join and aggregate queries, because one write can change many cached results. Write paths are also easy to miss. Bulk updates, migrations, backfills and other services writing to the same database all bypass your application's invalidation hooks.

Debugging also gets harder. A bug that appears only on hits, such as a stale serialized shape, will not reproduce against the database. A bug that appears only on misses will not reproduce once the key is warm.

Where it saves time

A narrow cache can postpone database scaling work, such as larger instances, sharding or new replicas. To keep it useful, cover a few measured hot queries and track the hit ratio. Build key versioning, TTLs and stampede protection on day one. Adding them later usually happens during an incident, when you have the least time to design them carefully.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to redis cache aside pattern, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.