Skip to content

[Hyperdrive] Document Postgres.js prepare: false pitfall - #33555

Draft
ivoryibu wants to merge 1 commit into
productionfrom
docs/hyperdrive-postgres-js-prepare-false
Draft

ivoryibu wants to merge 1 commit into
productionfrom
docs/hyperdrive-postgres-js-prepare-false

Conversation

@ivoryibu

Copy link
Copy Markdown
Collaborator

Summary

Adds a caution to the shared Hyperdrive driver recommendation note against setting prepare: false on a Postgres.js client. The note renders wherever Postgres.js is listed as supported: the supported drivers page and the Postgres.js and node-postgres driver pages.

With prepared statements disabled, Postgres.js sends additional protocol messages to discover parameter types before each query, which Hyperdrive's transaction pooling mode does not reliably support. This can cause individual queries to hang or fail intermittently while the connection pool otherwise appears healthy — a failure mode that is hard to attribute to the driver configuration. The caution directs readers to node-postgres (pg), which is already the recommended driver.

Prompted by a community report of intermittent query hangs with Postgres.js prepare: false behind Hyperdrive.

Possible follow-up: the Drizzle ORM page note says node-postgres and Postgres.js are both "supported and compatible" — worth qualifying there too, since Drizzle with the Postgres.js driver may not use named prepared statements by default.

Documentation checklist

@github-actions github-actions Bot added product:hyperdrive Hyperdrive: https://developers.cloudflare.com/hyperdrive/ size/xs labels Sep 21, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Preview URL: https://2b01117f.preview.developers.cloudflare.com
Preview Branch URL: https://docs-hyperdrive-postgres-js-prepare-false.preview.developers.cloudflare.com

@cloudflare-workers-and-pages

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://docs-hyperdrive-postgres-js-prepare-false.previews.developers.cloudflare.com (commit 2b01117)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://6eb55bd3.previews.developers.cloudflare.com 2b01117 2026-09-21T03:54:39.464Z Visit the dashboard ↗

@rzazadebilal7

Copy link
Copy Markdown

@rzazadebilal7

Copy link
Copy Markdown

Mene kömək edin onu düzəldə ideal iwlesin

@cloudflare-docs-bot

Copy link
Copy Markdown
Contributor

@ivoryibu This draft pull request has had no activity for 3 days. It will close after 7 days of inactivity. Transition to ready for review if ready. A codeowner can comment /draft-never-stale to keep it open.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

product:hyperdrive Hyperdrive: https://developers.cloudflare.com/hyperdrive/ size/xs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants