thomasgauvin: update docs for cache status volatile, stable functions#28536
Conversation
thomasgauvin
requested review from
a team,
Oxyjun,
elithrar and
sejoker
as code owners
github-actions
bot
added
product:hyperdrive
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
|
/bonk fix the build issues, review and address any findings |
Co-authored-by: thomasgauvin <thomasgauvin@users.noreply.github.com>
SummaryBuild status: All CI checks pass — Fix applied: Updated changelog link text in Review of all 4 changed files: This is a solid PR that improves Hyperdrive documentation around query caching behavior for
No MDX syntax issues, no unescaped special characters, no broken links, no heading hierarchy violations, no missing imports. Content is technically accurate and well-written. |
| description: Hyperdrive marks queries containing STABLE PostgreSQL functions as uncacheable, preventing stale cached results. | ||
| products: | ||
| - hyperdrive | ||
| date: 2026-02-13 |
There was a problem hiding this comment.
note - needs new date - also for file name
| date: 2026-02-13 | ||
| --- | ||
|
|
||
| Hyperdrive treats queries containing PostgreSQL `STABLE` functions as uncacheable, in addition to `VOLATILE` functions. |
There was a problem hiding this comment.
Add "now"? - Hyperdrive now treats
|
@Maddy-Cloudflare Bonk workflow was cancelled. View workflow run · To retry, trigger Bonk again. |
|
|
||
| Hyperdrive treats queries containing PostgreSQL `STABLE` functions as uncacheable, in addition to `VOLATILE` functions. | ||
|
|
||
| Previously, only functions that PostgreSQL categorizes as `VOLATILE` (for example, `RANDOM()`, `LASTVAL()`) were detected as uncacheable. `STABLE` functions (for example, `NOW()`, `CURRENT_TIMESTAMP`, `CURRENT_DATE`) were incorrectly allowed to be cached. |
There was a problem hiding this comment.
Worth linking to this? - https://www.postgresql.org/docs/current/xfunc-volatility.html
Or something like it?
| @@ -0,0 +1,19 @@ | |||
| --- | |||
| title: Queries using STABLE PostgreSQL functions are no longer cached | |||
There was a problem hiding this comment.
I'd name Hyperdrive in the title since the changelog is global
|
/bonk address the issues in comments |
Co-authored-by: mikenomitch <mikenomitch@users.noreply.github.com>
|
All checks pass. Here's a summary of the changes made to address all four review comments:
|
|
|
||
| Hyperdrive now treats queries containing PostgreSQL `STABLE` functions as uncacheable, in addition to `VOLATILE` functions. | ||
|
|
||
| Previously, only functions that PostgreSQL categorizes as [`VOLATILE`](https://www.postgresql.org/docs/current/xfunc-volatility.html) (for example, `RANDOM()`, `LASTVAL()`) were detected as uncacheable. `STABLE` functions (for example, `NOW()`, `CURRENT_TIMESTAMP`, `CURRENT_DATE`) were incorrectly allowed to be cached. |
There was a problem hiding this comment.
/bonk change the link to be on "that PostgreSQL categorizes" instead of on VOLATILE
Co-authored-by: mikenomitch <mikenomitch@users.noreply.github.com>
|
The link has been moved from |
| **Stable or volatile PostgreSQL functions in your query**: Queries that contain PostgreSQL functions categorized as `STABLE` or `VOLATILE` are not cacheable. Common examples include `NOW()`, `CURRENT_TIMESTAMP`, `CURRENT_DATE`, `RANDOM()`, and `LASTVAL()`. To resolve this, move the function call to your application code and pass the result as a query parameter. For example, instead of `WHERE created_at > NOW()`, compute the timestamp in your Worker and pass it as a parameter: `WHERE created_at > $1`. Refer to [Query caching](/hyperdrive/concepts/query-caching/) for a full list of uncacheable functions. | ||
|
|
||
| If your queries are not getting cached despite Hyperdrive having caching enabled, your driver may be configured such that your queries are not cacheable by Hyperdrive. This may happen if you are using the [Postgres.js](https://github.com/porsager/postgres) driver with [`prepare: false:`](https://github.com/porsager/postgres?tab=readme-ov-file#prepared-statements). To resolve this, enable prepared statements with `prepare: true`. | ||
| **Function names in SQL comments**: Hyperdrive uses text-based pattern matching to detect uncacheable functions. References to function names like `NOW()` in SQL comments cause the query to be treated as uncacheable, even if the function is not actually called. Remove any references to uncacheable function names from your query text, including comments. |
There was a problem hiding this comment.
| **Function names in SQL comments**: Hyperdrive uses text-based pattern matching to detect uncacheable functions. References to function names like `NOW()` in SQL comments cause the query to be treated as uncacheable, even if the function is not actually called. Remove any references to uncacheable function names from your query text, including comments. | |
| - **Function names in SQL comments**: Hyperdrive uses text-based pattern matching to detect uncacheable functions. References to function names like `NOW()` in SQL comments cause the query to be treated as uncacheable, even if the function is not actually called. Remove any references to uncacheable function names from your query text, including comments. |
src/content/changelog/hyperdrive/2026-02-23-hyperdrive-stable-functions-uncacheable.mdx
Outdated
Show resolved
Hide resolved
Co-authored-by: Maddy <130055405+Maddy-Cloudflare@users.noreply.github.com>
Co-authored-by: Maddy <130055405+Maddy-Cloudflare@users.noreply.github.com>
thomasgauvin
deleted the
thomasgauvin-hyperdrive-volatile-stable-functions-cache-clarification
branch
6 participants
No description provided.