Many small reads, a few huge invalidations: what I learned alongside Symfony Cache on Redis Cluster
On our e-commerce API, we invalidate a few hundred cache entries all the time, and that is easy with any cache. But switching the active catalogue means invalidating around a million entries at once, and that has to be fast too. With the first version of my cache, it blocked everything else for minutes, five minutes in the worst case. Nobody understood what was happening; the business and the customers saw it. So, how do you invalidate a million cache entries fast? Tags are the means, not the goal: a few thousand of them cover all these entries, as long as invalidating a tag does not mean visiting each entry.
Answering that question led me to RedisCacheWithPreload, my own little Redis cache class, running in production next to Symfony Cache instead of through one of its pools. It is specific to our use case, not a library to adopt, and I do not want to keep it. I tried another design to see where it could beat the existing one, so that what works goes back into Symfony, is there by default for everybody in 8.3, and I can return to stock Symfony Cache.
This post started as a note to Nicolas Grekas, who maintains the component, to explain all that. “It was faster” is not an answer you give to a maintainer, so I built a lab and measured everything.
Astuce
TL;DR, four things you can do on Monday:
- Batch your misses:
getItems(), one loader for everything that is missing,saveDeferred(),commit(). - Compress your values: wire
DeflateMarshaller, it is off by default. - On Redis Cluster, count round trips, not milliseconds: a multi-key read costs one round trip per slot, even with a single shard.
- Pick your tag adapter by the size of your invalidations: versions (
TagAwareAdapter) when a tag covers many entries, Sets (RedisTagAwareAdapter) for small tags whose memory must be freed right away.
And before writing your own cache, go read how TagAwareAdapter works.
Three questions will guide us:
- Where can another design beat Symfony Cache, for our workload? On one point, maybe two.
- What did trying teach me? A lot, starting with the bugs in my own class.
- What does Symfony Cache already get right? A lot, including compression, which is there but off by default.
Everything was measured on Symfony 6.4 (what runs in production), 8.1 and the upcoming 8.2, against a standalone server and a cluster with replicas. The servers run Valkey, the open-source fork of Redis that ElastiCache runs for us; it speaks the same protocol, so “Redis” below means either. The lab, its commands and its limits are described at the end, in How the lab works. Nicolas has since answered with pull requests: they are listed in What I asked for, and what happened next.
Contents:
- The workload
- One configuration, three topologies
- Three Redis adapters, two ideas of what a tag is
- Reading 100 keys, in four steps
- Compressing values: off by default
- Invalidating a million entries, and the race that comes with versions
- What trying taught me
- What Symfony gets right
- What I asked for, and what happened next
- So, can I delete my class?
- Appendices: every pull request, DSN and connections, compression, bans, key prefixes, how the lab works
Section intitulée the-workloadThe workload
Let’s start with the endpoint. It receives a list of product identifiers (EANs) and returns one rendered product per known EAN:
POST /products/by-eans
{"eans": ["3600000000011", "3600000000028", "…"]}
200 OK
{"products": [
{"ean": "3600000000011", "properties": { … }},
{"ean": "3600000000028", "properties": { … }}
]}
properties is the rendered product: it is the expensive part, and it is what gets cached, one entry per EAN and per context (site, locale, currency…).
The shape of the load: at peak, hundreds of thousands of reads per minute, of about 10 items each. On the invalidation side, small ones (a few hundred entries) all the time, big ones every week, and huge ones (around a million entries at once) up to about 20 times a year.
Three facts drive everything else, so let’s take the time to explain them:
- A miss is expensive. Building one product needs SQL queries and an HTTPS call to another service: about 3 ms when Varnish has the answer, about 30 ms when it does not.
- Entries are invalidated by tag, and the request does not know the tag. A tag is a label attached to a cache entry, so that entries can be invalidated as a group. Here, every entry built from a product carries that product’s tag:
fr-EUR-3600000000011anden-USD-3600000000011(the same EAN in two contexts), and the entries of the other EANs of that product, are all taggedproduct-42(names simplified). When product 42 changes, a single “banproduct-42” invalidates all of them, without having to list them. The catch: the request gives me EANs, and finding which product, and therefore which tag, an EAN belongs to is a SQL query. I do not want to run that query just to read the cache, so the cache itself has to remember the tag of each key. - Invalidations are mostly small, sometimes huge, and tags are what makes the huge ones cheap. About 90 % of the bans touch two tags, a few hundred entries: easy, whatever the cache. But when the active catalogue switches (we call it a workspace switch), the diff between the two catalogues is banned at once. That is around a million cache keys, but at most about 5,000 tags: going through tags is the only way to keep that operation small, and the whole point of this post is that it must be fast. Those are the bulks that blocked production: the first version of my class deleted every entry of a banned tag. Since it versions its tags instead of deleting entries, the same bulks are fast and invisible in production. And ideally I want to go one step further and compute the entries of the next catalogue before the switch, which requires cache keys I can guess in advance.
Section intitulée one-configuration-three-topologiesOne configuration, three topologies
The same code runs on a standalone Redis in dev, on ElastiCache Serverless in staging, and on an ElastiCache cluster (one shard, two replicas) in production. And this is where Symfony Cache shines: the pool configuration never changes, only the DSN does. I love that.
# config/packages/framework.yaml
framework:
cache:
default_redis_provider: '%env(REDIS_DSN)%' # also injectable as the cache.default_redis_provider service
app: cache.adapter.redis
# dev: standalone
REDIS_DSN=redis://valkey:6379
# staging, ElastiCache Serverless: one endpoint, cluster protocol, TLS
REDIS_DSN=rediss://<name>.serverless.euw3.cache.amazonaws.com:6379/0?persistent=1&redis_cluster=1&failover=slaves
# production, ElastiCache cluster mode enabled: configuration endpoint, 1 shard (1 primary + 2 replicas)
REDIS_DSN=redis://<name>.clustercfg.euw3.cache.amazonaws.com:6379/0?persistent=1&redis_cluster=1&failover=slaves
Symfony builds a \Redis for the first DSN and a \RedisCluster for the other two, and failover=slaves sends every read-only command to a replica: in the lab, 100 % of the reads of Symfony pools were served by replicas (the other failover modes are compared in the appendix). My class does not open its own connection: it injects the one Symfony built from default_redis_provider, through the cache.default_redis_provider service. That is why it lives next to Symfony Cache rather than instead of it. The details (Serverless, failover modes, option names, how to inject that connection, and how to do the same for a second DSN) are in Appendix: DSN and connections.
Section intitulée three-redis-adapters-two-ideas-of-what-a-tag-isThree Redis adapters, two ideas of what a tag is
Symfony Cache ships three ways to put a cache in Redis and, honestly, their names did not help me to tell them apart. It all comes down to one question: how do you invalidate, at once, every entry linked to a product?
framework:
cache:
pools:
plain: { adapter: cache.adapter.redis } # RedisAdapter
versioned: { adapter: cache.adapter.redis, tags: true } # TagAwareAdapter around a RedisAdapter
sets: { adapter: cache.adapter.redis_tag_aware } # RedisTagAwareAdapter
RedisAdapterhas no tags: a key/value pool,MGETto read,SETEXto write. To invalidate, you must know and delete every key.TagAwareAdapteradds tags on top of any pool (Redis, filesystem, APCu…) by versioning them. A tag’s version is a random value, stored as an ordinary item of the pool. When an entry taggedproduct-42is saved, Symfony reads the current version ofproduct-42, or draws one if the tag has none yet, saya1b2, and copies it into the entry’s metadata. On every read, it fetches the current versions of the entry’s tags (a second fetch, skipped for versions the same process has read in the last 0.15 s) and compares them with the recorded ones: if they match, it is a hit. Invalidatingproduct-42deletes its version, and nothing else (TagAwareAdapter.php#L121-L131): the entries tagged with it stay in the pool until their TTL, but thea1b2they carry no longer matches anything, so they count as misses. The next save draws a new version, and only entries written from then on are served. Because the version is random rather than a counter, a version lost to eviction cannot come back with an old value and revive stale entries.RedisTagAwareAdapteris Redis-only and does the opposite: it keeps, for each tag, a Redis Set of the keys tagged with it. Invalidating a tag deletes every entry of the Set, inside a Lua script (RedisTagAwareAdapter.php#L277-L374).
TagAwareAdapter (versions) |
RedisTagAwareAdapter (Sets) |
|
|---|---|---|
| write | the entry stores its tags’ versions in its metadata | SETEX the entry, SADD its key to each tag’s Set |
| read | MGET the entries, then MGET their tags’ versions |
one MGET, no check |
| invalidate a tag | UNLINK the tag version key |
Lua: walk the Set, DEL each entry |
| cost of a ban | grows with the number of tags | grows with the number of entries |
| memory after a ban | stale entries stay until their TTL | freed at once |
| constraints | none | eviction policy volatile-* or noeviction, so that Sets are never evicted; Sets keep references to expired entries (prune() since 8.2) |
Picture TagAwareAdapter changing the lock: the old keys still exist, they open nothing anymore, and they expire on their own. RedisTagAwareAdapter throws the boxes away: it has to know where each one is, and carry them out one by one. The first is made for bans of many entries, the second for small tags when memory must be reclaimed right away. My class belongs to the first family, as we will see.
Section intitulée reading-100-keysReading 100 keys
Let’s simulate one request in the lab: 100 identifiers, each mapped to one tag, a 2.6 KB serialized model per entry (743 bytes once gzipped). That is ten times our usual request, on purpose: it makes the differences easy to see. “Warm” means everything is cached, “cold” means nothing is.
Section intitulée step-1-code-cacheinterface-get-code-in-a-loopStep 1: CacheInterface::get() in a loop
Let’s begin with the idiomatic Symfony way:
$models = [];
foreach ($ids as $id) {
$models[] = $cache->get("variant-$id", function (ItemInterface $item) use ($id) {
$item->expiresAfter(3600);
$item->tag("product-$id");
return $this->loader->load([$id])[$id]; // SQL queries + one HTTPS call, for one item
});
}
It works, but it reads one key per call: 100 round trips when everything is cached, 200 with tags (each get() also fetches the tag versions). And there is worse: the callback can only compute one item at a time. On a cold cache, the 100 HTTPS calls happen one after the other. Ouch.
Section intitulée step-2-code-getitems-code-one-batch-load-code-savedeferred-codeStep 2: getItems() + one batch load + saveDeferred()
PSR-6 lets you do much better. Of the four things in the TL;DR, this is the one that changes response times the most:
$items = $pool->getItems($keys); // one MGET
$missing = [];
foreach ($items as $key => $item) {
if (!$item->isHit()) {
$missing[$key] = $item;
}
}
foreach ($this->loader->load(array_keys($missing)) as $key => $model) { // batched SQL + HTTPS calls in parallel
$pool->saveDeferred($missing[$key]->set($model)->tag(…));
}
$pool->commit(); // one pipeline
saveDeferred() only queues the item in memory: nothing is sent to Redis until commit(), which writes every queued item at once (one pipeline on a standalone Redis). Calling save() in the loop would send one write per item.
Before you copy this loop, know what it leaves behind: get() comes with stampede protection (a lock around the callback, so that concurrent requests do not all compute the same missing value) and early expiration. getItems() has neither. If the same keys can go cold for many requests at once, that is yours to handle.
What does it change once the HTTPS calls are part of the picture? The lab has a small HTTP service that answers after 3 or 30 ms; the batch loader calls it for every missing item at once with curl_multi, while the get() callback only ever sees one item.
One warning before the table: the batched variants are given as one range, on purpose. They moved by up to 60 ms between two runs of the same benchmark, about as much as what separates them, so time cannot rank them. That does not mean they are all equal: step 3 ranks them, on round trips.
p50 per request of 100 items, in milliseconds, on the cluster, Symfony 8.2:
| strategy | 30 ms upstream, 100 misses | 30 ms, 10 misses | 3 ms, 100 misses | 3 ms, 10 misses |
|---|---|---|---|---|
get() loop, RedisAdapter |
3266 | 344 | 461 | 52 |
get() loop, TagAwareAdapter |
3325 | 403 | 561 | 101 |
getItems() + batch, any of the three adapters, or my class |
59 to 123 | 35 to 64 | 20 to 32 | 7 to 16 |
The get() loop rows did not move between runs.
The lesson has nothing to do with Redis: compute your misses as a batch. From 3.3 seconds to around 100 ms: it is the largest drop in response time of this whole post, and it works with Symfony Cache as it is. The callback API of CacheInterface::get() does not allow it, PSR-6 does, and my class makes it the only way to use it. Once the misses are batched, what is left? Round trips.
Section intitulée step-3-what-is-left-on-a-clusterStep 3: what is left on a cluster
On a standalone Redis, step 2 is unbeatable: 1 round trip warm, 2 cold (MGET, then a pipeline of SETEX). With TagAwareAdapter it is 2 warm (items, then tag versions) and 4 cold. Job done, nothing to add.
On a cluster, the picture changes completely. RedisTrait::doFetch() calls mget() on the \RedisCluster (RedisTrait.php#L553-L584). phpredis splits a cluster MGET by slot and, outside of MULTI, sends each sub-command and waits for its reply before sending the next one (redis_cluster.c#L419-L450). Our 100 keys live in about 100 different slots: that is 100 sequential round trips, even on a single-shard cluster, because the split is per slot, not per node. Writes are no better: Symfony’s pipeline() helper falls back to one command at a time for \RedisCluster, as phpredis cannot pipeline across a cluster (RedisTrait.php#L758-L767).
Same code, same 100 keys, round trips per request (identical on Symfony 6.4, 8.1 and 8.2):
| strategy | standalone warm | cluster warm | standalone cold | cluster cold |
|---|---|---|---|---|
get() loop, RedisAdapter |
100 | 100 | 200 | 200 |
get() loop, TagAwareAdapter |
200 | 200 | 400 | 400 |
getItems() + batch, RedisAdapter |
1 | 100 | 2 | 200 |
getItems() + batch, TagAwareAdapter |
2 | 200 | 4 | 400 |
getItems() + batch, RedisTagAwareAdapter |
1 | 100 | 3 | 300 |
RedisCacheWithPreload, all its keys in one slot |
1 | 1 | 2 | 2 |
The last line looks great, but it comes with a price: every key of the class lives in the same cluster slot. Step 4 explains how, and what it costs.
Round trips are what you pay for in AWS. With a 0.5 ms round trip between the PHP container and the cache node (a plausible cross-AZ figure, not something I measured here), 200 round trips add at least 100 ms to a request, whatever Redis does. Even in the lab, where a round trip costs tens of microseconds, the warm TagAwareAdapter read takes 8.8 ms p50 on the cluster against 1.2 ms on the standalone instance.
Section intitulée step-4-what-code-rediscachewithpreload-code-doesStep 4: what RedisCacheWithPreload does
So what does my class do? It keeps the shape of step 2 (one batch loader for all the misses) and moves the tag resolution into Redis. Its get(), simplified:
// RedisCacheWithPreload::get(), simplified pseudo-code
$keys = array_map($keyClosure, $items);
$cached = $this->runScript(READ_SCRIPT, $keys); // 1 round trip, on a replica
$missing = /* items whose key is not in $cached */;
if ($missing) {
$preloaded = $preloadClosure($missing); // one batch: SQL + parallel HTTPS calls
foreach ($missing as $item) {
$value = $computeClosure($item, $preloaded);
$tag = $tagsClosure($item)[0] ?? null; // the tag is only known after loading
if (null !== $value && null !== $tag) {
$toWrite[] = [$key, $tag, $ttl, gzdeflate(serialize($value))];
}
}
$this->runScript(WRITE_SCRIPT, $toWrite); // 1 round trip, on the primary
}
return /* cached and computed values, in input order */;
And the read script, also simplified:
-- KEYS: key-tags hash, tag-versions hash. ARGV: the logical keys of the request.
local tags = redis.call('HMGET', KEYS[1], unpack(ARGV)) -- key → tag
local versions = redis.call('HMGET', KEYS[2], unpack(uniqueTags)) -- tag → current version
-- build 'cache:{tag_versions}:data:<key>::v::<version>' for every key whose tag has a version
local values = redis.call('MGET', unpack(dataKeys))
-- return the hits as (key, value) pairs; everything else is a miss
Before going further, we need two Redis Cluster notions:
- Slots and shards. A cluster spreads keys over 16,384 slots; the slot of a key is a hash of its name. A shard is a primary with its replicas, and each shard owns a range of slots. A command or a script that touches several keys only works if all of them hash to the same slot: that is why phpredis cuts an
MGETinto one command per slot, even when one shard owns every slot, as in our production. - Hash tags. When a key name contains
{…}, only the part between the braces is hashed. Every key that shares{tag_versions}therefore lands in the same slot, whatever the rest of its name. This{…}has nothing to do with cache tags; the name is unfortunate.
A Symfony pool cannot use hash tags: { and } are among the characters PSR-6 reserves in keys, and RedisAdapter refuses them in its namespace. Symfony only uses one internally, in RedisTagAwareAdapter, to keep the temporary Set of an invalidation in the slot of the tag’s Set.
Storage is made of three things, all under the {tag_versions} hash tag:
cache:{tag_versions}:key-tags, a hash: logical key → tag;cache:{tag_versions}:tag-versions, a hash: tag → version;cache:{tag_versions}:data:<logical key>::v::<version>, the gzipped, serialized value.
The version of the tag is part of the name of the data key. That is what turns a ban into a version bump, and what makes keys guessable: a key, a tag and a version are enough to name an entry before it exists. It is also why a read needs the tag: to find an entry, I first need the current version of its tag.
All of this data lives in one slot, on purpose. Look at the three key names above: they all contain {tag_versions}. Redis Cluster only hashes the part between braces to pick the slot, so cache:{tag_versions}:key-tags, cache:{tag_versions}:tag-versions and every cache:{tag_versions}:data:… key get the same hash, hence the same slot, whatever comes after. Nothing else is needed: no configuration, no special command, just that part of the name. And since every key the read script touches is in that one slot, the cluster accepts the script, and the 100 sequential round trips become one. Our production cluster has a single shard today (one primary, two replicas), so this costs nothing yet.
Do not take “put a hash tag everywhere” away from this post. Pinning data to one slot has a price:
- no sharding for this data: the day we add shards, none of it will move to them;
- every write goes to one primary;
- read capacity only grows through the replicas.
Reads: one script, one round trip. A read is one EVALSHA_RO of a Lua script that does HMGET key-tags, HMGET tag-versions, builds the versioned keys and runs a single MGET, all on the server. This is where fact #2 matters: the request knows the EAN, not the tag, and the script resolves “EAN → tag → current version → value” without SQL and without knowing the tag up front. To be fair to Symfony, TagAwareAdapter does not need the tag up front either: it reads the tags from the item metadata and checks their versions after the fetch (TagAwareAdapter.php#L145-L212). The difference is not “SQL or no SQL”, it is that second fetch: one more round trip on a standalone server, one more round trip per slot on a cluster.
Writes: one more script. Once the batch loader has run, a second script receives every computed value with its tag and TTL, and for each one reads the tag’s version (creating it if needed), records the key → tag link and writes the entry under that version, atomically, on the primary. null results and items without a tag are not written at all: nothing could ever read them back. Invalidating a chunk of tags is a third script: one round trip for the 50 tags of a Messenger message. Invalidating means bumping versions: old entries are not deleted, they are simply never read again and expire with their TTL. That is TagAwareAdapter's family, with the version in the key name instead of the value.
Replicas: one trap. Because the read script never writes, it is sent with EVALSHA_RO, and with failover=slaves phpredis routes it to a replica: in the lab, 100 % of the warm reads of the class were served by replicas, in one round trip. I fell into a trap on the way. The script cache is not part of the dataset: it is a volatile, per-node cache, and since Redis 7.0 scripts are only replicated by their effects (the write commands they run), never by their source (Scripting with Lua). In the lab, neither an EVAL nor a SCRIPT LOAD on a primary made the script appear on its replica. So the first EVALSHA_RO on each replica answers NOSCRIPT, and the fallback matters:
$response = $this->redis->evalsha_ro($sha, $args, 2);
if (false === $response) {
// NOSCRIPT: EVAL_RO stays on the same replica and caches the script there.
// A plain EVAL is a write command: it goes to the primary, and the replica never learns the script.
$response = $this->redis->eval_ro($luaScript, $args, 2);
}
With eval() as the fallback, which is what I had first, every read went to a replica, failed, and was replayed on the primary: two round trips, and not a single read served by the replicas. With eval_ro(), each replica pays one NOSCRIPT after a start, a failover or a node replacement, then serves everything. Redis Functions would avoid the problem altogether, since they are replicated and persisted (a FUNCTION LOAD on the primary did show up on the replica in the lab), but phpredis 6.3's RedisCluster has no fcall_ro(), so there is no way to route them to replicas from PHP today.
Section intitulée compressing-values-off-by-defaultCompressing values: off by default
My class stores gzdeflate(serialize($value)). That was not a design choice, it was a fix. Without compression, the bandwidth of our ElastiCache nodes kept growing and their “Engine CPU” metric (the CPU used by the Redis engine itself) sat at 100 %. With compression, the payloads are small and the engine sleeps: that metric dropped by about 80 %. That is a production observation, not a lab result, and a different kind of gain from the batching above: batching cut the response time of requests with misses, compression relieved the servers. And since all of this data lives on one shard, its three nodes carry all of it: every write on the primary, every read on the two replicas.
Symfony Cache does not compress by default. Its default marshaller only serializes. On the lab’s fixture (product models with natural-looking text, URLs, identifiers; your ratio will differ), gzdeflate() divides a 2609-byte model by 3.5, to 743 bytes. For a warm read of 100 models, Valkey sent 256 KB per request to getItems() on an uncompressed RedisAdapter, and 74 KB once the pool used DeflateMarshaller, the same as my class (81 KB including its keys). The price is CPU on the PHP side: about 12 µs per value to decompress, 2 ms for the 100 values of the request. On ElastiCache Serverless the bytes are also the bill: according to the pricing page, a read or a write costs 1 ECPU per kilobyte transferred (a request under 1 KB still costs 1 ECPU, and commands that need more CPU cost more), and stored data is billed per GB-hour.
So if your cache is read-heavy with kilobyte-sized values: turn it on! Symfony has shipped DeflateMarshaller since 5.3, but you have to know it exists and wire it yourself. Decorating the default marshaller compresses every pool:
# config/services.yaml
services:
Symfony\Component\Cache\Marshaller\DeflateMarshaller:
decorates: cache.default_marshaller
arguments: ['@.inner']
Since FrameworkBundle 8.1 you can also compress only some pools, with the pool’s marshaller option. The read tables above compare uncompressed Symfony pools with my compressed class: round trips do not change with compression, timings do by the amount above. Compression levels and phpredis’ own compression are in Appendix: compression.
Section intitulée invalidating-a-million-entriesInvalidating a million entries
Here is the scenario that started it all: a workspace switch, a million entries to invalidate, and thousands of tags to do it. The lab populates entries through each public API (one tag per entry), then invalidates every tag by chunks of 50, like our Messenger handler does, while another client sends PING to every primary in a loop. A slow PING means the server was busy doing something else.
Standalone Valkey with its default settings (lazyfree-lazy-user-del yes), 1000 tags × 1000 entries (1 million entries), then 5000 tags × 200 entries:
| stack | ban duration | commands on the server | PING p50 / max during the 1000 × 1000 ban |
memory after the 1000 × 1000 ban |
|---|---|---|---|---|
TagAwareAdapter |
14 ms / 67 ms | 20 / 100 UNLINK (tag keys only) |
0.26 ms / 0.58 ms | unchanged (173 MB) |
RedisTagAwareAdapter |
2.0 s / 2.5 s | 1,001,000 DEL inside Lua, plus SSCAN, SUNIONSTORE… |
58.6 ms / 166 ms | freed (2.7 MB) |
RedisCacheWithPreload |
11 ms / 54 ms | 20 / 100 scripts (1000 / 5000 HINCRBY inside) |
0.35 ms / 2.2 ms | unchanged (212 MB) |
Valkey Cluster (3 shards), 1000 tags × 200 entries, then 5000 tags × 40 (a ban only sends write commands, which go to primaries whatever the failover option):
| stack | ban duration | commands on the primaries | PING max |
|---|---|---|---|
TagAwareAdapter |
51 ms / 326 ms | 1000 / 5000 UNLINK |
0.7 ms / 2.4 ms |
RedisTagAwareAdapter |
7.3 s / 9.3 s | ~133k UNLINK sent by PHP + ~70k DEL inside Lua |
3.4 ms / 5.5 ms |
RedisCacheWithPreload |
4 ms / 22 ms | 20 / 100 scripts (1000 / 5000 HINCRBY inside) |
0.14 ms / 0.76 ms |
This is the version-versus-Set split, now with numbers. TagAwareAdapter and my class stay in the milliseconds, whatever the number of entries, and leave stale entries in memory until their TTL. RedisTagAwareAdapter reclaims memory immediately, but its work grows with the number of entries: on a standalone server the script runs atomically, one tag at a time, and other clients waited 58 ms on median during the ban; on a cluster, the entries live on other nodes than the tag Set, so most of them are deleted from PHP, one UNLINK at a time, and the ban takes seconds. A couple of side questions (DEL or UNLINK, ElastiCache Serverless) are answered in Appendix: bans.
A word on UNLINK, often presented as the non-blocking DEL: here it is not really asynchronous. UNLINK still removes the key from the keyspace at once, inside the command. What it can hand to a background thread is freeing the value’s memory, and only for values made of many allocations: Valkey frees in the background when that effort exceeds 64, and a string counts for 1 (lazyfree.c). Our values are small strings, a few hundred bytes once compressed, so there is nothing to defer. Deleting a million keys is a million operations either way, and inside one Lua script no other client is served until they are done. In the lab, replacing DEL with UNLINK in that script took the ban from 3.0 s to 2.4 s (one run each): a bit better, still blocking. The payload is light; the number of keys is the problem.
For our bans, TagAwareAdapter would have done the job. What it does not offer is to choose the next version. My invalidateTags() accepts one, and the workspace switch passes the start timestamp of the new workspace, while TagAwareAdapter creates a random version (random_bytes(6)) the first time a tag is needed after a ban (TagAwareAdapter.php#L385-L397). A predictable version is what would allow computing the entries of the next workspace before the switch. That is a possibility, not a result: I have not built it yet. It is the main reason I kept versions under my control.
A note on the tables above: they show HINCRBY because the lab bans without giving a version, and in that case the class increments the current one. When a version is given, as the workspace switch does, the same script does an HSET with that value instead. The cost is the same: one write per tag.
Section intitulée the-race-that-versioned-tags-must-not-loseThe race that versioned tags must not lose
Versioning tags has one trap, and of course I fell into it. On a miss, the class reads the current version of the tag, then writes the entry under that version. My first version did this from PHP, in separate commands, and then wrote the version back with HSET to create it when the tag had none. If a ban lands between the read and the write-back, the write-back puts the old version back, and every entry cached before the ban comes back to life until its TTL:

And it happens precisely when it hurts: right after a big ban, when every worker recomputes misses on the tags that were just banned. With failover=slaves the HGET was also served by a replica that may lag behind the primary, which widened the window. The lab measures it with lab:race: one process caches a value, bans its tag and checks whether the old value is still served, 1000 times, while other processes compute misses on the same tag.
| write path | concurrent writers | bans lost out of 1000 (standalone) | (cluster, failover=slaves) |
|---|---|---|---|
first version: HGET, SET, HSET from PHP |
1 | 564 | 522 |
first version: HGET, SET, HSET from PHP |
4 | 678 | 741 |
write script: HSETNX + HGET + SET, atomic |
1 | 0 | 0 |
write script: HSETNX + HGET + SET, atomic |
4 | 0 | 0 |
With the write script: 0 ban lost. On the primary, atomically, it only creates a version for a tag that has none, reads the current one, and writes the entry under it. It never writes back a version it read, which is exactly what TagAwareAdapter has always done; Symfony loses 0 bans out of 1000 in the same test.
-- never write back a version we read: create it only if missing, then use the current one
redis.call('HSETNX', KEYS[2], tag, defaultVersion)
local version = redis.call('HGET', KEYS[2], tag)
redis.call('SET', CACHE_PREFIX .. logicalKey .. VERSION_SEPARATOR .. version, value, 'EX', ttl)
The difference between the two commands is the whole fix. HSET tag-versions T v1 writes v1, whatever the hash already holds: if a ban has just replaced the version, HSET silently undoes it. HSETNX (“set if not exists”) only writes when the tag has no version at all, and leaves an existing one untouched. A writer can therefore create the first version of a tag, but never overwrite the version a ban has set.
Section intitulée what-trying-taught-meWhat trying taught me
This is the humbling section. Every item below was reproduced with a command of the lab, and every one of them was a bug or a blind spot of mine. Two have already been told above: reads that skipped the replicas (EVAL_RO) and bans that got lost (the write script). The others:
- One expired entry made the following ones miss. The first read script walked the
MGETresults with an index that was only incremented on hits: if the entry ofbexpired in a batcha, b, c, d,canddwere recomputed too. The lab reproduced[b, c, d]instead of[b]; it now recomputes[b]only. - Misses cost 4 round trips each, not pipelined: 401 round trips for 100 misses, and 120 s to populate one million entries. With the write script: 2 round trips for 100 misses, 15 s for a million entries (
TagAwareAdapter: 11 s). nullresults were written and never read back. The read side usedisset(), andisset()is false fornull. Yes, the very bug I wrote about in 2020. Entries without a tag had the same fate. Now neither is written.- Invalidation sent one command per tag; it is now one script per chunk of tags.
- The connection was taken from the pool by reflection; it is now injected (see the appendix).
Still open:
- Metadata never shrinks. The
key-tagshash has no TTL and gets one field per logical key, forever. cache:pool:cleardoes not see these keys. They are written with the raw client, outside of the pool namespace: in the lab,cache:pool:clear --allleft all of them in place.- A source change during a computation stores the stale result under the new version. This one is shared with Symfony: both my class and
TagAwareAdapterservev2-computed-from-old-datain the lab. Only a lock, or a version check at write time, would fix it.
You know the famous quote from Phil Karlton: “There are only two hard things in Computer Science: cache invalidation and naming things.” I can confirm the first one. A cache looks like twenty lines of code, and the hard part is everything around them. Races between readers and invalidations, replicas that do not know your scripts, values that expire in the middle of a batch, metadata that grows forever, keys that cache:pool:clear cannot see. Symfony Cache has years of bug reports and fixes behind it on exactly these points.
Section intitulée what-symfony-gets-rightWhat Symfony gets right
Here is what the lab showed Symfony Cache doing well, often better than my class:
- One DSN, every topology. Standalone, ElastiCache Serverless and a replicated cluster with the same pool configuration, replica routing included. My class only works on all three because it borrows Symfony’s connection.
- Tag versioning without races.
TagAwareAdapterbans in a number of commands that depends on the number of tags, not entries, and lost 0 bans out of 1000 where my first version lost more than half. I ended up copying its rule. - Writes.
getItems()+saveDeferred()+commit()pipelines every write on a standalone server: a million entries in 11 s. My first version took 120 s; it took a Lua script to get down to 15 s. - Batching is already possible. PSR-6 lets you load all misses at once: that alone took a cold request from 3.3 s to around 100 ms.
- Compression is built in, if you turn it on.
DeflateMarshallerdivides the bytes by 3.5 (see Compressing values). - Safe key prefixes by default, with an off switch. Every pool prefixes its keys with a namespace, so two apps, two environments or two pools sharing one Redis can never overwrite each other’s keys. The default namespace depends on the project directory, which cools the whole cache at each release on Capistrano-style deployments; one line of configuration,
prefix_seed, fixes it. Details in Appendix: key prefixes. - The details nobody thinks about. Keys stay inside the pool namespace and
cache:pool:clearworks;nullis a cacheable value; stampede protection and early expiration come withget();RedisTagAwareAdapterrefuses an eviction policy that would corrupt its tag sets, and recent releases recognize ElastiCache Serverless.
Section intitulée what-i-asked-for-and-what-happened-nextWhat I asked for, and what happened next
The first draft of this post ended with a list of things I wished Symfony Cache had: the ones that would let me delete my class. I shared it with Nicolas Grekas in private, as a gist, on 22 October 2026. Nobody owed me an answer: Symfony is open source, I had gone my own way with a homemade class, and a wish list is easy to write.
The next day, Nicolas had started opening pull requests. Thirteen so far, plus an RFC: in Symfony itself, in its documentation, and even in phpredis, to fix the round trips at their source rather than work around them. A batch API, smarter compression, bounded invalidation scripts, new documentation, and a few bugs found and fixed on the way. He did not just read the post: he checked it, took what was right, left what was not, and went further than I had asked.
So before the list: thank you, Nicolas. That is an incredible amount of work, and I do not take any of it for granted, whatever ends up merged. It is exactly why I love this community: you show up with a problem, and people give their time to make the framework better for everybody.
As of 10 November 2026, three of them change the story of this post:
- The batch loop becomes an API.
BatchCache(symfony#67371) fetches several keys and loads all the misses with one callback, on any PSR-6 pool, with an optional lock that reuses the stampede protection. - Cluster reads get cheaper at the source. Pipelining per node, in phpredis itself (phpredis#2963) and in Symfony (symfony#67353), would bring a cluster read from one round trip per slot down to one per node.
- Big bans stop blocking.
RedisTagAwareAdapterwould invalidate big tags in bounded scripts (symfony#67358), and the cost of a ban with each adapter is now documented (symfony-docs#23417, merged, along with compression andprefix_seed).
And it does not stop at Nicolas: Marcin Gil has since picked up the torch, with two libraries, three RFCs and a talk. Among other things, he proposes a tag-aware Redis adapter that versions its tags (symfony#68050), which is the idea behind my class as a real adapter. Every pull request, what became of each of my wishes and these follow-ups are in Appendix: every pull request.
The new features are milestoned for Symfony 8.3, not 8.2. I have not re-run the lab against these branches: every number in this post describes Symfony 6.4.47, 8.1.9 and 8.2.x-dev as of 19 October.
Section intitulée so-can-i-delete-my-classSo, can I delete my class?
Not yet, but that is the plan. Two things still keep it alive.
The first one is measured: reads on a cluster, in 1 round trip served by replicas instead of 100 to 200, by pinning the data to one slot and resolving “key → tag → version → value” in one Lua script. It only pays because of our workload (many keys per request on a Redis Cluster), and it costs the sharding of that data. The pull requests in review do not cover it yet: as written, phpredis#2963 keeps sequential execution when reads go to replicas (failover=slaves), which is our setup.
The second one is only a possibility: choosing the next version would let us compute the next workspace ahead of a switch. The class makes it possible; nobody has built it yet.
Everything else, Symfony already does as well or better, and I only saw how much once I had tried to redo it myself. And what worked is on its way back: a batch get(), cheaper cluster reads and bounded bans are in review for Symfony 8.3, and the rest is tracked in an RFC. The day they cover my case, replicas included, I delete RedisCacheWithPreload and go back to 100 % Symfony Cache. I can’t wait.
Section intitulée appendix-every-pull-requestAppendix: every pull request
State as of 10 November 2026. Six of Nicolas’ pull requests and the RFC cite the draft; the seven others are tied to those by reference (a prerequisite, a follow-up, a bug found on the way). The kind is the one declared in each pull request, and the version is the branch it targets.
| Pull request | What it does | Kind | State |
|---|---|---|---|
| symfony#67371 | BatchCache: fetch several keys and load all the misses with one callback, on any PSR-6 pool; an optional lock key reuses the stampede protection |
new feature | open (8.3) |
| symfony#67332 | DeflateMarshaller skips small or incompressible values and accepts a compression level; nesting it is deprecated |
new feature, deprecation | open (8.3) |
| symfony#67353 | use native RedisCluster pipelines when the extension has them (needs #67341 and phpredis#2798, by another contributor) |
new feature | draft (8.3) |
| symfony#67407 | keep the known tag versions when saving a value computed by TagAwareAdapter::get(), so that a concurrent invalidation still applies |
new feature | open (8.3) |
| symfony#67358 | RedisTagAwareAdapter invalidates big tags in bounded scripts, so that other clients run between batches |
performance | open (8.3) |
| symfony#67333 | with Predis Cluster, bulk reads use one pipeline per node | performance | open (8.3) |
| symfony#67574 | an item saved after a concurrent invalidation lost its tags and could never be invalidated by tag again | bug fix | merged (6.4), released in 6.4.49 and 8.1.10 |
| symfony#67341 | lazy Redis proxies with the development version of phpredis | bug fix | draft (6.4) |
| symfony#67412 | Relay Cluster: clearing a pool could skip nodes | bug fix | merged (7.4) |
| symfony#67413 | Relay Cluster: same when pruning tags | bug fix | merged (8.2) |
| symfony-docs#23417 | documents how to compress values, what a tag invalidation costs with each adapter, and prefix_seed for deployments that change directory |
documentation | merged (6.4) |
| symfony-docs#23416 | documents the bounded invalidation of #67358 | documentation | open (8.3) |
| phpredis#2963 | RedisCluster::mget() sends its per-slot batches to each node before reading the replies |
performance | open, not reviewed yet |
The RFC, symfony#67391, keeps track of three follow-ups: combining tag versions and Sets in RedisTagAwareAdapter, preventing a stale computation from repopulating the cache after an invalidation, and prewarming the changed products while keeping the shared cache.
And against my list, what became of each wish:
- A batch API: one fetch, one callback for all the misses, one save, without writing the PSR-6 loop by hand. That is
BatchCache(#67371). - A way to put a pool in one slot, since a pool cannot use hash tags. Not taken as such: the round trips are attacked from the other side, by pipelining per node (phpredis#2963, #67353, #67333), which would bring a cluster read from one round trip per slot down to one per node. One caveat for my setup: as written, phpredis#2963 only applies with the default failover mode. Its documentation says that “other failover modes keep sequential execution”, so reads sent to replicas with
failover=slaveswould not benefit yet. - Items and tag versions in one round trip. Tracked in the RFC (first point).
- Choosing the version on invalidation, to compute entries ahead of a planned ban. The RFC takes the need from another angle (third point: prewarm what changed).
- Document the cost of
RedisTagAwareAdapterbans. Done: symfony-docs#23417 is merged, and #67358 goes further by bounding the pauses, at the price of a longer total invalidation. UNLINKinstead ofDELin the invalidation script. Not taken, and rightly so: one run each way gave 3.0 s against 2.4 s, still blocking. #67358 addresses the blocking itself.- Make compression visible. Done: the same documentation pull request adds a “Compressing Cache Values” section, and #67332 makes the marshaller smarter.
Two things came out that I had not asked for. The race I listed as shared with Symfony (a source change during a computation) is the second point of the RFC and the subject of #67407. And a reader of the RFC reported a related bug in the Set-based adapters, which is now fixed (#67574).
Since then, Marcin Gil picked up the torch. He published two libraries for Symfony Cache, artigo/versioned-cache (tag invalidation in constant time, backed by Redis) and artigo/cache-stampede (stampede protection across the whole fleet), and on 9 and 10 November he opened three RFCs to bring them into Symfony, plus a first pull request, all open:
- symfony#68050 follows the first point of the RFC: a tag-aware Redis adapter that versions its tags, so that an invalidation does not walk the entries, while reads keep the round trips of
RedisTagAwareAdapter. That is the idea behind my class, as a real adapter. - symfony#68051 and symfony#68052 go further than anything in this post: a stampede protection that spans all the servers, and serving the old value while one request refreshes it (stale-while-revalidate).
- symfony#68083 follows #67332 with a
ZstdMarshaller, milestoned for 8.3.
He also tells the whole road, from a file cache to versioned Redis, in an excellent talk: Teaching Websites When to Forget (slides online, for rg-dev #69 on 25 November 2026).
I have not tested any of them. But a wish list shared in private turning into this many proposals, from several people, is the best outcome I could hope for.
Section intitulée appendix-dsn-and-connectionsAppendix: DSN and connections
Topologies. AbstractAdapter::createConnection() wraps the client in Symfony’s lazy RedisProxy / RedisClusterProxy. failover=slaves maps to phpredis’ RedisCluster::OPT_SLAVE_FAILOVER = FAILOVER_DISTRIBUTE_SLAVES (RedisTrait.php#L450-L455); failover=distribute spreads reads over primaries and replicas instead (about 50 % on replicas in the lab).
- ElastiCache Serverless is a special case: AWS documents that it surfaces every slot on a single virtual node and serves replica reads on a separate port, 6380. The lab cannot reproduce that, so everything in this post about replicas applies to the provisioned cluster, not to Serverless.
- Since Symfony 7.3 the options are named
clusterandsentinel;redis_clusterandredis_sentinelremain accepted aliases (RedisTrait.php#L200-L213). 7.3 also added thevalkey://scheme. 8.2 introduces aCacheBundlethat provides thecacheconfiguration previously found underframework.cache, with a newcache.default_provideroption. Theframework.cacheconfiguration above still worked unchanged on 8.2.x-dev in the lab. failoveronly exists for cluster clients (and Predis replication). With a non-clustered primary plus a reader endpoint and phpredis, Symfony has no way to send reads to the reader: declare a second pool with the reader DSN.
Getting the connection. My first version read the private redis property of the RedisAdapter with a bound closure (and unwrapped TraceableAdapter in debug mode):
// don't do this
$getter = fn ($name) => $this->$name;
$redis = $getter->call($pool, 'redis');
It works, but it depends on a private property name, on the decoration chain, and phpstan rightly hates it. Symfony already exposes the connection as a service. framework.cache.default_redis_provider is turned into a connection service built by AbstractAdapter::createConnection($dsn, ['lazy' => true]), aliased as cache.default_redis_provider, and that is the very object the Redis pools receive (CachePoolPass.php#L290-L306). Inject it:
public function __construct(
#[Autowire(service: 'cache.default_redis_provider')]
private readonly \Redis|\RedisCluster $redis,
) {
}
The lab checks it with lab:conn: on 6.4, 8.1 and 8.2, standalone and cluster, the injected object and the one hidden in the pool are the same instance (spl_object_id included), so there is still a single connection per DSN. For a second Redis with its own DSN, declare the connection as a named service and give it to the pool as its provider, so that both share it:
services:
app.redis.secondary:
class: Redis
factory: ['Symfony\Component\Cache\Adapter\RedisAdapter', 'createConnection']
arguments: ['%env(SECONDARY_REDIS_DSN)%', { lazy: true }]
framework:
cache:
pools:
app.cache.secondary:
adapter: cache.adapter.redis
provider: app.redis.secondary
The class only matters for autowiring: with a cluster DSN the factory returns a \RedisCluster proxy, hence the union type in the constructor.
Section intitulée appendix-compressionAppendix: compression
Measured with lab:payload on 1000 fixture models:
| encoding | bytes per model | ratio | µs to compress | µs to decompress |
|---|---|---|---|---|
serialize() |
2609 | 1.00 | – | – |
gzdeflate(), level 1 |
786 | 3.32 | 35 | 14 |
gzdeflate(), default level 6 |
743 | 3.51 | 43 | 12 |
On the standalone instance, a warm getItems() of 100 models went from 0.8 to 2.9 ms p50 once compressed; writes pay 43 µs per value, once. Level 1 compresses almost as well as the default level for less CPU. Without any configuration, Symfony’s DefaultMarshaller only serializes (with igbinary when available): compression is always opt-in, either by decorating cache.default_marshaller as shown above, or per pool with the marshaller option since FrameworkBundle 8.1. phpredis can compress natively too (lzf, zstd, lz4, when compiled with them), but RedisTagAwareAdapter refuses that and asks for DeflateMarshaller instead (RedisTagAwareAdapter.php#L76-L84).
Section intitulée appendix-bansAppendix: bans
DEL or UNLINK? TagAwareAdapter deletes its tag version keys through doDelete(), which uses UNLINK and only falls back to DEL if UNLINK fails (RedisTrait.php#L691-L723). The entries deleted inside RedisTagAwareAdapter‘s Lua script are deleted with DEL. Valkey 8 ships with lazyfree-lazy-user-del yes (that is what CONFIG GET returns in the lab), so there DEL already frees memory the way UNLINK does. With lazy freeing disabled, like Redis’ default, I patched the script to use UNLINK and ran the 1000 × 1000 ban once each way: 3.0 s and a 85 ms median PING with DEL, 2.4 s and 71 ms with UNLINK. One run each, so read it as “a bit better”, not as a fix: what blocks the server is walking a million keys inside one script, not freeing them.
This is also why the median PING here (85 ms with DEL) is higher than the 58.6 ms of the main table: that one was measured with Valkey’s default, lazy freeing enabled.
ElastiCache Serverless. RedisTagAwareAdapter refuses to save when it cannot detect a volatile-* or noeviction eviction policy, and ElastiCache Serverless does not report its policy. In the versions I first tested, 6.4.47 and 8.1.9, the policy resolves to an empty string and doSave() throws; I could not reproduce Serverless locally, so this comes from reading the code. It was fixed as a bug on the 6.4 branch (symfony#67036, merged on 18 October 2026, a few days before I shared the draft): 6.4.49 and 8.1.10 contain the detection (RedisTagAwareAdapter.php#L404-L416).
Section intitulée appendix-key-prefixesAppendix: key prefixes
Every pool prefixes its keys with a namespace, a hash of three things (CachePoolPass.php#L42-L85):
framework.cache.prefix_seed, which defaults to_%kernel.project_dir%.%kernel.container_class%;- the pool name;
- the adapter class.
The project directory is the catch. The kernel finds it from the real path of its own file (AbstractKernel.php#L194-L214), and PHP resolves symlinks when it loads a file:
| deployment | project directory seen by Symfony | namespace across releases |
|---|---|---|
Docker image, always run from /app |
/app |
stable |
Capistrano-style, served through current → releases/<date> |
releases/<date> |
new at each release |
In the lab, the same code booted through current wrote lAsiso3rNA:product-42 while current pointed to releases/20261020-1200, then +HI-rSPH5a:product-42 once it pointed to releases/20261022-0900. Every release starts with a cold cache, and the previous one’s keys linger until their TTL.
The fix is one line, and the default framework.yaml even ships it commented out:
framework:
cache:
prefix_seed: 'my-app/%kernel.environment%'
Section intitulée how-the-lab-worksHow the lab works
Versions: Symfony 6.4.47 (what runs in production), 8.1.9 and 8.2.x-dev (commit 1d70b55 of 2026–10–19), phpredis 6.3.0, PHP 8.5, Valkey 8.1.
The lab lives next to this post: a Docker Compose stack with a standalone Valkey, a 3-shard Valkey Cluster with one replica per shard, a fake slow HTTP service, and a tiny Symfony app that switches between the three Symfony versions. Every number comes from one of its commands: ./run <dev|serverless|prod> <64|81|82> lab:read, lab:ban, lab:race, lab:bugs, lab:dsn, lab:conn, lab:payload. The prod target uses the production DSN options (failover=slaves).
Round trips are counted on the server side (total_reads_processed and INFO commandstats on every node, with tiny payloads so that one request burst is one socket read); timings come from a local Docker network with no added latency. It runs on one machine, so absolute timings are optimistic; round trips and command counts are the numbers that carry over.
Commentaires et discussions
Ces clients ont profité de notre expertise
JoliCode a formé l’équipe de développement d’Evaneos aux bonnes pratiques pour l’écriture de tests unitaires efficaces et utiles. Nous en avons également profité pour mettre en place une plateforme d’intégration continue pour accompagner l’évolution de la plateforme.
Nous avons travaillé en étroite collaboration avec Cerfrance pour améliorer la qualité de leurs projets PHP et Symfony, tout en renforçant les compétences de leur équipe. Notre intervention a consisté à mettre en place une intégration continue (CI), à coacher l’équipe pour l’ajout de fixtures et de tests, à dockeriser l’application, et à installer…
Nous avons épaulé Adrenaline Hunter, juste avant le lancement public de ses offres, sur des problématiques liées à la performance de leur application développée avec Symfony. Nous avons également mis en place un système de workflow des commandes de séjours afin que toutes les actions avec leurs différents partenaires soient réparties avec fiabilité…