Query caching
Hyperdrive automatically caches the most popular queries executed against your database, reducing the need to go back to your database (incurring latency and database load) for every query.
Because Hyperdrive uses database protocols, it can differentiate between a mutating query (a query that writes to the database) and a non-mutating query (a read-only query), allowing Hyperdrive to safely cache read-only queries.
Besides determining the difference between a SELECT
and an INSERT
, Hyperdrive also parses the database wire-protocol and uses it to differentiate between a mutating or non-mutating query.
For example, a read query that populates the front page of a news site would be cached:
-- CacheableSELECT * FROM articlesWHERE DATE(published_time) = CURRENT_DATE()ORDER BY published_time DESCLIMIT 50
Mutating queries (including INSERT
, UPSERT
, or CREATE TABLE
) and queries that use functions designated as volatile
by PostgreSQL are not cached:
-- Not cachedINSERT INTO users(id, name, email) VALUES(555, 'Matt', 'hello@example.com');
SELECT LASTVAL(), * FROM articles LIMIT 50;
The default caching behaviour for Hyperdrive is defined as below:
max_age
= 60 seconds (1 minute)stale_while_revalidate
= 15 seconds
The max_age
setting determines the maximum lifetime a query response will be served from cache. Cached responses may be evicted from the cache prior to this time if they are rarely used.
The stale_while_revalidate
setting allows Hyperdrive to continue serving stale cache results for an additional period of time while it is revalidating the cache. In most cases, revalidation should happen rapidly.
You can set a maximum max_age
of 1 hour.
Disable caching on a per-Hyperdrive basis by using the Wrangler CLI to set the --caching-disabled
option to true
.
For example:
# wrangler v3.11 and above requirednpx wrangler hyperdrive update my-hyperdrive-id --origin-password my-db-password --caching-disabled true
You can also configure multiple Hyperdrive connections from a single application: one connection that enables caching for popular queries, and a second connection where you do not want to cache queries, but still benefit from Hyperdrive’s latency benefits and connection pooling.
For example, using the Postgres.js driver:
const client = new Client({ connectionString: env.HYPERDRIVE.connectionString,});// ...const noCachingClient = new Client({ // This represents a Hyperdrive configuration with the cache disabled connectionString: env.HYPERDRIVE_CACHE_DISABLED.connectionString,});
- Learn more about How Hyperdrive works.
- Learn how to Connect to PostgreSQL from Hyperdrive.
- Review Troubleshooting common issues when connecting a database to Hyperdrive.