skip to content

Why does a product listing read through Hyperdrive keep showing the old price for about a minute after an admin updates it, and how do you fix it?

level: seniorimportance: should knowfreq 30%

answer

  1. writes do not purge reads
  2. max_age plus the stale window
  3. check cacheStatus for hit
  4. a second, cache-disabled config

basics

~20 s

Hyperdrive never invalidates cached reads when a write happens, so the listing query returns its cached result until max_age (60 s by default) expires. Route reads that must be fresh through a second, cache-disabled Hyperdrive config, or shorten max_age.

solid answer

~40 s

The `UPDATE` reached the database, but Hyperdrive does not purge cached read results on writes. A matching `SELECT` keeps returning the cached response until `max_age` runs out (60 seconds by default) and may be served for up to 15 more seconds of `stale_while_revalidate`. The `cacheStatus` metric shows those reads as `hit`. The documented fix is a second Hyperdrive config for the same database, created with `--caching-disabled`, bound next to the cached one; reads that must be fresh, such as the admin's own view after the edit, authentication or permissions, go through it, while the public listing keeps its cache. If a short stale window is fine everywhere, lower `--max-age` and `--swr` instead. Remember both configs open their own origin connections.

code

bash · 1 line
bash
npx wrangler hyperdrive create products-db-fresh --connection-string="postgres://app_user:[email protected]:5432/catalog" --caching-disabled

go deeper

for a junior

Recall that Hyperdrive caches reads for 60 seconds by default and does not clear them when you write.

for a middle

Explain max_age and stale_while_revalidate, and how a second binding to a cache-disabled config gives fresh reads.

for a senior

Walk through the diagnosis with cacheStatus, pick which reads move to the fresh config, and account for both configs' origin connections.

for a principal

Turn it into a rule: classify reads by freshness need and make the cached path a deliberate choice rather than an accident.

## What happened Hyperdrive caches eligible **read** query results for the config's `max_age` and serves a later matching query from cache. The key fact is in its documentation: **Hyperdrive does not purge or invalidate cached read results when your application writes to the database.** So the sequence is: 1. The listing query ran a moment ago and its result was cached. 2. The admin's `UPDATE products SET price = $1 WHERE id = $2` went through Hyperdrive to the database and committed. Writes are never cached. 3. The next listing query matches the cached one, so Hyperdrive returns the old rows. 4. Only when `max_age` expires (60 seconds by default) does a fresh query reach the database, and during the following `stale_while_revalidate` window (15 seconds by default) the old result may still be served while Hyperdrive refreshes it in the background. Nothing is broken: the database is correct, and the Worker is seeing a cache that was told it may be up to a minute old. ## Confirming it - Hyperdrive's analytics report a `cacheStatus` per query. Stale reads show up as `hit`; a fresh read would show `miss` or `disabled`. - Query the database directly (outside Hyperdrive) and see the new price. - Wait out `max_age` and watch the listing correct itself. ## The fixes, from narrow to broad | Option | How | Trade-off | | --- | --- | --- | | Cache-disabled config for fresh reads | `wrangler hyperdrive create <name> --connection-string=... --caching-disabled`, bound as a second binding | two clients in code; both configs count against origin connections | | Shorter cache window | `wrangler hyperdrive update <id> --max-age <seconds> --swr <seconds>` | keeps caching for everyone, shrinks but does not remove staleness | | Turn caching off for the config | `wrangler hyperdrive update <id> --caching-disabled` | every read hits the database; pooling still helps | The **two-config pattern** is what the documentation recommends for mixed needs: ```json { "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "<cached config id>" }, { "binding": "HYPERDRIVE_CACHE_DISABLED", "id": "<cache-disabled config id>" } ] } ``` In the handler you create one client per binding: the public listing uses `env.HYPERDRIVE.connectionString`, and the admin's read-after-write, sessions, permissions and billing state use `env.HYPERDRIVE_CACHE_DISABLED.connectionString`. If an ORM or authentication library owns the SQL, hand it the cache-disabled client. The cache-disabled config still gives you Hyperdrive's edge connection setup and pooling, so fresh reads are not slow reads. ## Wiring the two clients ```javascript import postgres from "postgres"; export default { async fetch(request, env, ctx) { const cached = postgres(env.HYPERDRIVE.connectionString); const fresh = postgres(env.HYPERDRIVE_CACHE_DISABLED.connectionString); const url = new URL(request.url); if (request.method === "POST" && url.pathname === "/admin/price") { const { id, price } = await request.json(); await fresh`UPDATE products SET price = ${price} WHERE id = ${id}`; const [row] = await fresh`SELECT id, price FROM products WHERE id = ${id}`; return Response.json(row); } const rows = await cached`SELECT id, name, price FROM products ORDER BY name LIMIT 50`; return Response.json(rows); }, }; ``` The admin's confirmation read goes through the cache-disabled binding, so it shows the new price at once. The public listing still uses the cached binding and may lag by up to `max_age` plus the stale window, which is the trade the team accepted for that page. ## What not to do - **Do not rely on SQL comments as a cache-buster.** Hyperdrive does not document comments as a cache control. A comment without an uncacheable function name does not change the cache key, so two queries that differ only in comments share one cached result. - **Do not expect a write through the same config to refresh the cache.** It does not, whichever binding performs it. - **Do not forget the connection budget.** Each config has its own pool and origin connection limit; with two configs on one database, keep the sum under the database's own connection cap with some headroom, because the limit is soft. ## Choosing per read A practical rule: public, high-volume reads that tolerate a short delay (catalogue pages, search results, dashboards) go through the cached config with a deliberate `max_age`; anything a user just changed or anything that decides access goes through the cache-disabled one. If most reads turn out to need freshness, disabling caching on the single config is simpler than maintaining two clients everywhere.

  • Why not just set `max_age` very low on the single config?
    It shrinks the stale window but does not close it, and it lowers the hit ratio for the high-volume listing that benefits most from caching. A low value plus the `stale_while_revalidate` period still allows an old result after a write. Use the cache-disabled config where freshness is a correctness requirement and keep a useful `max_age` elsewhere.
  • Does the stale read mean the admin's write was lost?
    No. Hyperdrive sends writes to the database and only caches eligible reads, so the update committed. Reading through a cache-disabled config, or directly at the database, shows the new price; the listing corrects itself once the cached entry expires.

A shop prints its price list from the warehouse system once a minute. When the warehouse changes a price, the printed list at the counter stays wrong until the next print; a clerk who must quote the exact price phones the warehouse instead of reading the list.

  • Hyperdrive purges cached rows for a table when a write to that table passes through it.
  • The write must have failed, because the next read still shows the old value.
  • Adding a unique SQL comment is the supported way to force a fresh read through Hyperdrive.
  • A cache-disabled Hyperdrive config also loses connection pooling, so it is no faster than a direct connection.
  • Two Hyperdrive configs on one database share a single origin connection limit.