[Hyperdrive] Add query cache consistency guidance#31746
Conversation
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
There was a problem hiding this comment.
Review Summary
Overall: Approved with one minor suggestion. This is a well-scoped, clearly written documentation change.
What changed
- Documents that Hyperdrive does not invalidate cached reads after writes.
- Adds a new Read-after-write behavior section to the Query caching concept page with practical guidance on when to use caching vs. cache-disabled configurations.
- Renames example binding from HYPERDRIVE_CACHE_DISABLED to HYPERDRIVE_FRESH for clarity.
- Adds discovery points in FAQ, Troubleshooting, Get started, How Hyperdrive works, and PlanetScale pages.
- Re-formats several Markdown tables in troubleshooting.mdx for readability.
- Fixes US/UK spelling inconsistency (behaviour -> behavior).
Validation
- prettier --check passes on all 6 edited files.
- git diff --check passes.
- pnpm run check passes with 0 errors.
Minor suggestion
In troubleshooting.mdx, the "TLS handshake failed" row contains a pre-existing typo: "the expected the correct" should be "the expected correct" or "the correct". Since this PR is already reformatting that table, it would be a good time to fix the duplicate word.
|
Reviewed and approved PR #31746. Labels applied: Summary of changesThis PR adds clear guidance that Hyperdrive does not invalidate cached read results after writes, and shows users how to handle read-after-write consistency by using separate cache-disabled Hyperdrive configurations. Key changes across 6 files:
Validation
Flagged issueI noted one pre-existing typo in |
irvinebroque
left a comment
There was a problem hiding this comment.
Changes make sense, but wonder if we are repeating the same thing in slightly different ways across many places. See comemnts
| Hyperdrive uses text-based pattern matching to detect some uncacheable functions in your queries. This can include function names inside SQL comments. | ||
|
|
||
| For example, the following query would **not** be cached because `NOW()` appears in the comment: | ||
| Do not rely on comments such as `-- NOW()` or `-- RAND()` to bypass query caching. Hyperdrive does not document SQL comments as a cache-control API, and parser behavior can differ between database engines. Use a cache-disabled Hyperdrive configuration when you need a guaranteed fresh read. |
There was a problem hiding this comment.
refs guidance I got from Pranoy — @ivoryibu worth talking to him to make sure we've got this right
Summary
Validation
pnpm exec prettier --checkon edited MDX filesgit diff --checkpnpm run check:astrofails on existing generatedskills/turnstile-spinTypeScript files missingExportedHandlerandFetcher, unrelated to these docs changes.