What is the difference between a local cache and a Redis cache?

A local cache lives inside the application process. In a JVM monolith that usually means Caffeine: a concurrent hash map on the heap, holding object references. A Redis cache is a separate server. Every read is a network round trip plus serialization on write and deserialization on read, and your request path now depends on a remote service being up and responsive.

That cost gap is small for a single lookup but adds up quickly. A hot key such as tenant config, feature flags or a permissions set might be read dozens of times while serving one request. Locally, each read costs a hash lookup. Through Redis, each read pays the full network and decoding cost again. Hot keys are where a local tier helps most.

What each tier gives you

Caffeine:

  • Bounded size with frequency-aware eviction (Window TinyLFU), so a burst of one-off keys doesn't push out the hot ones.
  • Expire-after-write and expire-after-access policies.
  • Refresh-ahead, which reloads an entry asynchronously while still serving the stale value.
  • Loading caches that run the loader only once per key when concurrent requests miss in the same process.

Redis:

  • One view of the data shared by every instance.
  • Capacity beyond a single heap.
  • Data that survives application restarts and deploys. Surviving a Redis restart requires persistence to be configured.
  • Atomic operations for counters, rate limits and locks.
Property Local (Caffeine) Redis
Read cost In-process lookup, no serialization Network round trip plus deserialization
Scope One process All instances
Capacity Limited by heap Limited by Redis memory
Survives app restart No Yes
Stampede protection Per process Requires explicit locking
Atomic shared ops No Yes
Failure mode Dies with the process Separate dependency that can be slow or unavailable

Why should a monolith start with Caffeine before adding Redis?

Most caching in a monolith is memoization: the same process repeatedly asks for the same config row, permission set, or exchange rate. An in-process cache like Caffeine handles that with a library dependency and a few lines of configuration.

A minimal loading cache needs three settings:

  • Maximum size caps the number of entries. When the cap is reached, Caffeine evicts entries it predicts are least likely to be reused. Without a cap, the cache grows until the heap runs out.
  • Expire-after-write removes an entry a fixed time after it was loaded. This sets the longest time a stale value can be served.
  • Refresh-after-write marks an entry as eligible for reload after a shorter interval. The next read returns the current value and triggers an asynchronous reload, so callers don't wait on the database for hot keys. Set refresh below expiry. Refresh only happens on access, so rarely read keys still expire.

The costs land on the heap. Every entry is a live object that the garbage collector must trace. A large or high-cardinality cache, such as one keyed by user ID or search query, can lengthen GC pauses or cause an out-of-memory error. A limit based on entry count is misleading when value sizes vary: 10,000 small strings and 10,000 serialized reports use very different amounts of memory. Use maximum weight with a weigher to set the budget by approximate size instead. Each deploy or restart also starts with an empty cache, so the database absorbs a burst of misses.

In return, there is nothing to provision, no serialization format to choose, and no timeouts, retries, or network fallback paths to design and test.

import com.github.benmanes.caffeine.cache.Caffeine;
import com.github.benmanes.caffeine.cache.LoadingCache;
import java.math.BigDecimal;
import java.time.Duration;

public class RateCache {
    public record ExchangeRate(String pair, BigDecimal rate) {}
    public interface RateRepository { ExchangeRate findByPair(String pair); }
    public interface ReportRepository { byte[] renderReport(String reportId); }

    private final LoadingCache<String, ExchangeRate> rates;
    private final LoadingCache<String, byte[]> reports;

    public RateCache(RateRepository rateRepo, ReportRepository reportRepo) {
        this.rates = Caffeine.newBuilder()
            .maximumSize(10_000)                       // cap entry count; evicts entries least likely to be reused
            .expireAfterWrite(Duration.ofMinutes(10))  // longest time a stale rate can be served
            .refreshAfterWrite(Duration.ofMinutes(1))  // after 1 min, the next read returns the current value and reloads in the background
            .build(rateRepo::findByPair);              // loader runs on a miss or a refresh

        // Values vary widely in size, so budget by approximate bytes instead of entry count.
        // maximumWeight and maximumSize cannot be combined on one cache.
        this.reports = Caffeine.newBuilder()
            .maximumWeight(64L * 1024 * 1024)                 // about 64 MiB of report payloads
            .weigher((String id, byte[] body) -> body.length) // weight = payload size in bytes
            .expireAfterWrite(Duration.ofMinutes(5))
            .build(reportRepo::renderReport);
    }

    public ExchangeRate rate(String pair) {
        return rates.get(pair);    // loads on miss; concurrent callers for the same key share one load
    }

    public byte[] report(String reportId) {
        return reports.get(reportId);
    }
}

Two Caffeine loading caches: one capped by entry count with expire-after-write and refresh-after-write for small exchange-rate values, and one capped by total weight with a byte-length weigher for report payloads whose sizes vary.

When do you actually need Redis, and what does running N instances change?

Add Redis when a local cache can no longer meet one of four requirements:

  • Instances must share data. Sessions, rate-limit counters, and anything one instance writes and another must read.
  • The cache must survive deploys. A warm cache keeps the database from absorbing a burst of misses on every release.
  • Invalidation must be coordinated. One delete should affect every instance.
  • Operations must be atomic across instances. Examples are INCR, SET NX for locks, and expiring counters.

Running N instances also changes the math for a purely local cache. Illustrative estimate: with 10 instances and a 60-second TTL, each instance misses independently. That can mean up to 10 origin loads per minute per key, where one instance would cause 1. Because each copy expires on its own schedule, two instances can also return different values for up to 60 seconds.

Redis has its own costs. It adds a network dependency with a new failure mode, so you must decide what happens on an outage or timeout. Failing open means falling through to the origin, which risks overloading it. Failing closed means returning errors. Set timeouts deliberately, well below your request budget, and add circuit breaking so a slow Redis doesn't hold request threads.

Serialization costs CPU on every read and write. During rolling deploys, old and new code read the same keys, and a changed class shape can break deserialization. Put a schema or version prefix in keys to avoid this. Finally, a hot key lives on a single shard or node, so its traffic concentrates there no matter how large the cluster is.

How does a two-level cache work?

A two-level cache puts an in-process cache in front of Redis, so the hottest reads never leave the JVM:

request → L1 (Caffeine, per instance) → L2 (Redis, shared) → database

The read path checks the tiers in that order. On an L1 hit, return immediately. On an L1 miss, issue a Redis GET against a versioned key such as v3:user:42. If L2 hits, deserialize the value, put it into L1, and return it. If L2 also misses, load from the database, write to Redis with SET and an expiry, then populate L1. Fill the tiers from the bottom up so that L1 never holds a value that L2 lacks.

Set the L1 TTL much shorter than the L2 TTL, for example seconds against minutes. L1 is the tier you cannot reach directly. Once a value sits in the heaps of twelve instances, no single delete removes it everywhere. A short L1 TTL limits how long an instance can serve a value that Redis has already replaced. The longer L2 TTL keeps database load low.

L1 fixes the hot-key problem from the previous section, because repeated reads of one key stay in local memory and never reach its Redis shard. The cost is that it brings back cross-instance inconsistency, which a shared Redis had removed. A value can now be stale in L1, in L2, or in both, and each case has a different cause and a different fix. Treat a two-level cache as a consistency design you have to work out, not as a speed boost you get for free.

import com.github.benmanes.caffeine.cache.Cache;
import com.github.benmanes.caffeine.cache.Caffeine;
import java.time.Duration;
import java.util.function.Function;
import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisPool;

public class TwoLevelCache {
    // Bump the prefix to invalidate every L2 entry at once after a schema/format change.
    private static final String KEY_PREFIX = "v3:";
    private static final int L2_TTL_SECONDS = 600;  // minutes in Redis: protects the database

    // L1 TTL is seconds: bounds how long one instance can serve a value Redis has replaced.
    private final Cache<String, String> l1 = Caffeine.newBuilder()
            .maximumSize(10_000)
            .expireAfterWrite(Duration.ofSeconds(10))
            .build();

    private final JedisPool redis;
    private final Function<String, String> dbLoader; // returns the serialized value, e.g. JSON

    public TwoLevelCache(JedisPool redis, Function<String, String> dbLoader) {
        this.redis = redis;
        this.dbLoader = dbLoader;
    }

    public String get(String id) {
        String key = KEY_PREFIX + "user:" + id;
        String value = l1.getIfPresent(key);       // 1. L1 hit: no network round trip
        if (value != null) return value;

        try (Jedis jedis = redis.getResource()) {
            value = jedis.get(key);                // 2. L1 miss: ask the shared tier
            if (value == null) {
                value = dbLoader.apply(id);        // 3. L2 miss: go to the source of truth
                if (value == null) return null;    // don't cache absent rows in this sketch
                jedis.setex(key, L2_TTL_SECONDS, value); // fill L2 first...
            }
        }
        l1.put(key, value);                        // ...then L1, so L1 never holds what L2 lacks
        return value;
    }
}

A read-through sketch using Caffeine as L1 and Redis via Jedis as L2: it checks L1, then a versioned Redis key, then the database, fills the tiers bottom-up, and gives L1 a much shorter TTL than L2.

How do you keep a two-level cache consistent across instances?

Three strategies are common for invalidating L1 when another instance changes the data.

Short TTLs alone cap staleness at the TTL and need no coordination. You pay for this with a lower hit rate.

Broadcast invalidation publishes the changed key over Redis pub/sub or a similar channel, and every instance evicts that key from its local cache. Eviction is near-immediate, but pub/sub is fire-and-forget. Messages are neither persisted nor acknowledged, so an instance that is reconnecting misses them silently. Always keep a TTL as a backstop.

Versioned keys embed a version, such as user:42:v7, that you bump on write. Old entries become unreachable and expire on their own. However, every read must first fetch the current version.

Strategy Staleness bound Complexity Failure behaviour
Short TTL only TTL Low Degrades predictably
Pub/sub broadcast Milliseconds, else TTL Medium Dropped messages leave stale entries until TTL
Versioned keys Version lookup freshness Medium–high Version store outage blocks or staleness

On the write path under cache-aside, commit to the database and then delete the cache entry. Updating the entry in place lets two concurrent writers set values out of order.

Even delete-after-commit has a race:

  1. A reader misses the cache and reads the old row.
  2. The writer commits and deletes the entry.
  3. The reader then writes the stale value into the cache.

The TTL bounds how long this stale value survives.

Cache-aside cannot give strong consistency. Data such as balances and permission checks should bypass the cache and read from the database.

import threading
import redis
from cachetools import TTLCache

r = redis.Redis(host="localhost", port=6379)
CHANNEL = "cache-invalidate"
l1 = TTLCache(maxsize=10_000, ttl=30)
l1_lock = threading.Lock()

def listen_for_invalidations():
    pubsub = r.pubsub(ignore_subscribe_messages=True)
    pubsub.subscribe(CHANNEL)
    for msg in pubsub.listen():
        # Pub/sub is fire-and-forget: anything published while this instance is disconnected is lost
        with l1_lock:
            l1.pop(msg["data"].decode(), None)

threading.Thread(target=listen_for_invalidations, daemon=True).start()

def get_user(user_id, db):
    key = f"user:{user_id}"
    with l1_lock:
        if key in l1:
            return l1[key]
    raw = r.get(key)
    if raw is None:
        raw = db.fetch_user_json(user_id)  # may read a row that a writer is about to change
        r.set(key, raw, ex=300)  # the L2 TTL bounds how long a stale repopulation survives
    with l1_lock:
        l1[key] = raw
    return raw

def update_user(user_id, fields, db):
    key = f"user:{user_id}"
    with db.transaction():
        db.update_user(user_id, fields)
    # Delete after commit instead of overwriting, so concurrent writers cannot leave values out of order
    r.delete(key)
    r.publish(CHANNEL, key)  # every instance, including this one, evicts the key from L1

A cache-aside write path that deletes the Redis entry after the database commit and broadcasts an L1 eviction over pub/sub, with TTLs on both cache levels as a backstop for lost messages and the stale-reader race.

How do you prevent cache stampedes at each tier?

When a hot key expires, every request that misses at that moment goes to the origin at once. In a monolith with N instances the same thing happens N times, because each process has its own L1 and its own herd.

L1: coalesce inside the process

A Caffeine loading cache allows only one load per key at a time. Concurrent callers for the same key wait on that single computation, so a process sends at most one request per key to L2 or the database. refreshAfterWrite reduces the waiting further. After the refresh interval passes, callers still get the current value while one background reload replaces it, so a hot key does not go through a blocking miss.

L2: spread expiry and elect one loader

  • Jittered TTLs. Add a random offset, for example base TTL ±10%, so keys written together do not all expire in the same second.
  • Probabilistic early refresh. Each reader has a small chance of reloading the key before it expires. That chance rises as expiry approaches, so usually one reader refreshes it ahead of time.
  • A short lock. On a miss, run SET lock:key <token> NX PX 5000. The winner loads the value, writes it, and deletes the lock only if the token still matches. Losers sleep briefly and read again. If the holder crashes, the expiry frees the lock. Set it longer than a normal load, or two loaders can overlap.

The example below shows a jittered write and a lock-guarded reload.

Deploys

A rolling deploy starts every new instance with an empty L1, one batch after another. A warm L2 absorbs these misses. Bumping the key-format version empties both tiers, so each batch hits the origin again. To prevent that, warm the hot keys before the instance reports ready.

import json, random, secrets, time
import redis

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

BASE_TTL_S = 300   # nominal lifetime of a cached value
LOCK_MS = 5000     # must exceed a normal origin load, or two loaders can overlap

release_lock = r.register_script("""
if redis.call('GET', KEYS[1]) == ARGV[1] then
  return redis.call('DEL', KEYS[1])
end
return 0
""")

def jittered_ttl(base=BASE_TTL_S, spread=0.10):
    # +/-10% so keys written together do not all expire in the same second
    return int(base * random.uniform(1 - spread, 1 + spread))

def get(key, load_from_origin, attempts=50):
    lock_key = f"lock:{key}"
    for _ in range(attempts):
        cached = r.get(key)
        if cached is not None:
            return json.loads(cached)
        token = secrets.token_hex(16)
        # NX elects one loader; PX frees the lock if that loader crashes
        if r.set(lock_key, token, nx=True, px=LOCK_MS):
            try:
                value = load_from_origin(key)
                r.set(key, json.dumps(value), ex=jittered_ttl())
                return value
            finally:
                release_lock(keys=[lock_key], args=[token])
        # Lost the race: back off briefly, then re-read what the winner wrote
        time.sleep(0.05 + random.random() * 0.05)
    raise TimeoutError(f"cache fill for {key!r} did not complete")

A redis-py read path that writes values with a jittered TTL and uses SET NX PX with a token-checked release so only one process reloads a missing key from the origin.

When should you avoid caching, and how do you choose a placement?

Some data should not be cached at all. If correctness depends on freshness, as with account balances, stock levels at checkout, or permission checks, read from the source of truth. A slow query is often fixed more cheaply with an index or a rewrite than with a cache that you then have to keep consistent. When the same lookup repeats within one request, per-request memoization is enough. Adding Redis to a monolith that only needs that memoization means provisioning, monitoring, eviction policy, and security work for almost no gain.

Data characteristics Placement Why
Write-heavy, or freshness affects correctness No cache; fix the query or add an index Invalidation cost exceeds read savings
Read-heavy, global, small values, low cardinality, seconds of staleness tolerable Local only Fastest reads, no network hop
Per-user or high cardinality, large values, needs one invalidation point Redis only Avoids duplicating the data in every heap
Hot global keys, many instances, expensive origin Two-level L1 absorbs hot reads, L2 shields the origin
Repeated lookups within a single request Per-request memoization Lives and dies with the request

Measure these before and after any change:

  • Hit rate for each tier.
  • Origin load rate.
  • Heap usage and GC impact of the local cache.
  • Redis latency at p50 and p99.
  • How often instances disagree, which you can estimate by sampling keys against the origin.

If L1 already absorbs most reads and the origin is comfortable, the data shows that an L2 tier would add little, so you avoid building and operating it.

Who should use a local cache, Redis, or both?

Use a local cache only if you run a monolith on one instance or a few, and the cached data is small, read-heavy, and can be a few seconds stale. Typical examples are configuration, feature flags, reference tables, and exchange rates. Teams without dedicated operations capacity benefit most, because the cache is a library dependency and adds no service to run.

Use Redis only if several instances must see the same value, such as sessions, rate-limit counters, or distributed locks. It also fits data that is too large or too high-cardinality to copy into every heap, and data where one delete must take effect everywhere. Your team needs to be able to run Redis as production infrastructure, including monitoring, capacity planning, failover, and access control, or you need a managed equivalent.

Use both if you run many instances, have hot global keys that concentrate on one Redis shard, and the origin is expensive to load from. Your team also has to accept the extra consistency design described above. If no one owns invalidation and staleness budgets, a two-level cache will produce stale-data bugs that are hard to reproduce.

Use neither if the data is write-heavy, correctness depends on freshness, or the real problem is a missing index or an inefficient query.

What are the alternatives to a local or Redis cache?

Before adding either tier, check whether a different approach fixes the underlying problem:

  • Fix the query. Add an index, remove an N+1 access pattern, or fetch only the columns you need. These changes need no invalidation logic.
  • Per-request memoization. Store results in a request-scoped map so repeated lookups within one request run once. This avoids staleness across requests entirely.
  • Database-side options. Read replicas spread read load across servers, but replication lag is a staleness source of its own. Materialized views or precomputed summary tables cover expensive aggregations. The database's own buffer cache already keeps hot pages in memory, so a cache in front of it helps less than people expect for simple primary-key lookups.
  • HTTP caching. For responses that are the same across users, Cache-Control headers and a reverse proxy or edge cache can serve repeated requests before they reach the application.
  • Other distributed in-memory key-value stores. These fill the same role as Redis for shared caching. Feature sets differ, especially atomic operations, data structures, and persistence, so compare them against the four requirements listed earlier.
  • Other in-process caching libraries. Most JVM caching libraries offer size bounds and TTLs, and many stacks have equivalents. Check that the one you pick supports per-key load coalescing and refresh-ahead before relying on it for hot keys.
  • Loading data at startup. Small, rarely changing reference data can be loaded into memory when the application starts and reloaded on a schedule or when an explicit signal arrives, without a general-purpose cache.

How can the right cache placement save engineering time?

Most of the engineering cost of caching comes after it is in place, in operations, invalidation bugs, and incident response, not in writing the first version. Choosing the smallest tier that meets the requirement reduces that cost in several ways:

  • No infrastructure work when a local cache is enough. Caffeine needs no provisioning, network configuration, credentials, failover testing, or Redis-specific monitoring and alerting. Engineers configure a builder and move on.
  • Fewer failure modes to design and test. A local-only cache has no timeouts, retries, circuit breakers, or fail-open versus fail-closed decisions to make. Each one you skip is code you never write, review, or debug.
  • Less consistency debugging. Stale-data bugs across instances are slow to reproduce. Applying a two-level cache only to the hot keys that need it, with explicit TTL budgets, limits the number of places where those bugs can occur.
  • Built-in stampede protection. Loading caches with per-key coalescing and refreshAfterWrite replace hand-written locking for the in-process tier. You only build the lock-and-jitter logic for L2 if you actually run L2.
  • Measurement before building. Tracking hit rates, origin load, and Redis latency first tells you whether a new tier is worth building. If L1 already absorbs most reads, you skip the work of building and operating L2.
  • Versioned keys and warm-up for deploys. A key prefix and pre-ready warm-up prevent deserialization failures and origin load spikes during rolling deploys, which removes a common class of release-day incidents.

Illustrative estimate, using assumed inputs: assume a team spends a few days building and testing Redis integration (client configuration, timeouts, circuit breaking, serialization, versioned keys), plus a recurring amount of time each month on monitoring, upgrades, and cache-related incidents. If measurement shows that a local cache meets the requirement, that whole setup cost and the recurring cost are avoided. If Redis is required, adding it only for the data that needs sharing or atomicity keeps the recurring cost limited to that data. Replace the assumed inputs with your own team's figures before using this in a decision.

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 local cache vs redis cache, 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.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

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.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • 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.