Which read queries does Hyperdrive leave uncached even with query caching enabled, and how do you make a frequent listing query cacheable?
answer
- only reads with fixed inputs
- function volatility decides
- NOW() in the WHERE clause
- pass the timestamp as a parameter
- prepare: false costs the cache
basics
~20 sHyperdrive caches only non-mutating reads. Writes, queries calling STABLE or VOLATILE PostgreSQL functions such as NOW() or RANDOM(), results over 50 MB and Postgres.js with prepare: false stay uncached; compute values in the Worker and pass them as parameters.
solid answer
~40 sHyperdrive parses the database wire protocol to tell writes from reads and caches eligible read responses for `max_age` (60 seconds by default, with a 15-second `stale_while_revalidate` window). It skips writes, and since February 2026 it treats queries containing PostgreSQL `STABLE` functions (`NOW()`, `CURRENT_DATE`, `CURRENT_TIMESTAMP`) as uncacheable alongside `VOLATILE` ones (`RANDOM()`, `LASTVAL()`); only `IMMUTABLE` functions are compatible. Detection is partly text matching, so even a function name in an SQL comment can make a query uncacheable. Responses over 50 MB are returned but not cached, and Postgres.js with `prepare: false` loses caching and adds round trips. To fix a listing query, compute the time in the Worker and bind it as `$1`, keep `prepare: true`, and confirm with the `cacheStatus` metric.
code
sql · 7 lines-- Not cached: NOW() is a STABLE function
SELECT id, name, price FROM products
WHERE published_at <= NOW() ORDER BY published_at DESC LIMIT 50;
-- Cacheable: the Worker binds a rounded cut-off as $1
SELECT id, name, price FROM products
WHERE published_at <= $1 ORDER BY published_at DESC LIMIT 50;go deeper
Know that Hyperdrive caches reads only, by default for 60 seconds, and that time functions in a query stop it caching.
Explain the volatility rule, the STABLE change of 2026, and how to rewrite a query to bind its time value as a parameter.
Diagnose a low hit ratio from cacheStatus values, never-repeating parameters, comments and driver settings such as prepare: false.
Treat cacheability as a query-design rule the team reviews, and weigh origin load against how stale each read may be.
## How Hyperdrive decides what to cache **Query caching** is on by default for every Hyperdrive config. Hyperdrive reads each query at the wire-protocol level and classifies it as **mutating** (a write) or **non-mutating** (a read). Only eligible reads are cached; a later query that matches a cached one gets the stored response without a trip to the origin database. The defaults are: - `max_age` = **60 seconds**, the longest a response is served from cache (you can raise it to at most **1 hour**); - `stale_while_revalidate` = **15 seconds**, extra time a stale response may be served while Hyperdrive refreshes it; - a cached response may be evicted before `max_age` if it is rarely used. Wrangler sets these per config with `--max-age` and `--swr`, or turns caching off with `--caching-disabled`. ## What stays uncached | Query shape | Cached? | Why | | --- | --- | --- | | `INSERT`, `UPDATE`, `DELETE`, `CREATE TABLE` | No | mutating queries are never cached | | A read calling `NOW()`, `CURRENT_DATE`, `CURRENT_TIMESTAMP` | No | PostgreSQL marks these `STABLE` | | A read calling `RANDOM()`, `LASTVAL()`, `TIMEOFDAY()` | No | PostgreSQL marks these `VOLATILE` | | MySQL reads calling `NOW()` or `LAST_INSERT_ID()` | No | non-deterministic results | | A read whose result is larger than 50 MB | No | returned to the Worker but not stored | | A read with only parameters and `IMMUTABLE` functions | Yes | same inputs, same answer | Two less obvious cases: 1. **Function names in comments.** Hyperdrive uses text-based pattern matching to spot some uncacheable functions, so a comment such as `-- uses NOW() upstream` can mark a query uncacheable even though nothing calls the function. Comment text without such names does not change the cache key, so two queries differing only in a harmless comment share one cached entry. 2. **Driver settings.** Postgres.js defaults to `prepare: true`. Some query builders and `sql.unsafe()` set `prepare: false`, and then Hyperdrive does not cache the statements and needs extra round trips; the docs also warn that this mode can hang or fail intermittently under Hyperdrive's transaction pooling. ## Rewriting a listing query The classic culprit is a product-listing query that filters by the current time: ```sql -- Uncached: NOW() is STABLE SELECT id, name, price FROM products WHERE published_at <= NOW() ORDER BY published_at DESC LIMIT 50; -- Cacheable: the Worker computes the cut-off and binds it SELECT id, name, price FROM products WHERE published_at <= $1 ORDER BY published_at DESC LIMIT 50; ``` For the second form to produce cache hits, the bound value must repeat. Passing `new Date()` with millisecond precision makes every query unique, so round the cut-off (for example to the start of the current minute) in the Worker before binding it. The same move applies to `CURRENT_DATE`: compute the date in code and pass it as a parameter. ## Where cached results live Since December 2024 Hyperdrive caches query results in all Cloudflare locations and answers a hit from the nearest cache, which is why a hit is much faster than a pooled query. A few practical points follow from how the cache is described: - A hit does not touch the origin database or a pooled connection, so a high hit ratio also eases pressure on the origin connection limit. - `max_age` is a ceiling, not a promise: a rarely used entry can be evicted earlier and the next query becomes a miss. - Caching does not reduce the query count used for plan limits; every query through Hyperdrive counts, cached or not. ## Checking the result Hyperdrive's analytics break queries down by `cacheStatus`. Besides `hit`, `miss` and `disabled`, it reports reasons such as `uncacheable`, `volatile`, `transaction`, `multiplestatements` and `oversizedresult`, which tells you which rule a query is tripping. A listing query reported as `volatile` still contains a time or random function; one that shows `miss` on nearly every call often binds a parameter that never repeats. ## What changed recently Before February 2026 Hyperdrive detected only `VOLATILE` functions, so queries using `NOW()` and other `STABLE` functions were cached. That could serve results computed for an earlier moment, and Hyperdrive now treats them as uncacheable. A team that relied on those hits loses them, and the documented remedy is to move the time calculation into the Worker and pass it as a parameter.
- Why can a cacheable query still show almost no cache hits?Hyperdrive serves a hit only for a matching query. If a bound parameter changes on every call, such as a timestamp with millisecond precision or a per-request ID, each query is a new entry and misses. Round or normalise parameters for shared reads, and remember that `max_age` caps how long any entry lives.
- Do cached queries cost less on the Workers Free plan?No. The Free plan allows 100,000 Hyperdrive database queries a day, and cached and uncached queries, reads and writes all count the same toward it. Caching saves origin load and latency, not quota.
- Hyperdrive caches every SELECT, whatever functions it calls.
- Adding a random comment to a query is a supported way to bypass Hyperdrive's cache.
- Query caching must be switched on before Hyperdrive caches anything.
- Results over 50 MB fail because Hyperdrive cannot cache them.
- Setting prepare: false in Postgres.js makes Hyperdrive caching more effective.
As of the 2026-02-23 Hyperdrive change, queries with STABLE PostgreSQL functions such as NOW() are uncacheable; before it only VOLATILE functions were excluded.