From 2b01117ff0a46f1fb4000af343a1b83e8cdd500a Mon Sep 17 00:00:00 2001 From: Ivory Date: Sun, 20 Sep 2026 22:39:08 -0500 Subject: [PATCH] [Hyperdrive] Document Postgres.js prepare: false pitfall --- .../partials/hyperdrive/node-postgres-recommendation.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/content/partials/hyperdrive/node-postgres-recommendation.mdx b/src/content/partials/hyperdrive/node-postgres-recommendation.mdx index 05cda0e5683..de728e1331d 100644 --- a/src/content/partials/hyperdrive/node-postgres-recommendation.mdx +++ b/src/content/partials/hyperdrive/node-postgres-recommendation.mdx @@ -7,3 +7,9 @@ [Node-postgres](https://node-postgres.com/) (`pg`) is the recommended driver for connecting to your Postgres database from JavaScript or TypeScript Workers. It has the best compatibility with Hyperdrive's caching and is commonly available with popular ORM libraries. [Postgres.js](https://github.com/porsager/postgres) is also supported. ::: + +:::caution[Do not use `prepare: false` with Postgres.js] + +[`prepare: false`](https://github.com/porsager/postgres?tab=readme-ov-file#prepared-statements) disables prepared statements. Postgres.js then sends additional protocol messages to discover parameter types before each query. Hyperdrive's [transaction pooling mode](/hyperdrive/concepts/how-hyperdrive-works/#pooling-mode) does not reliably support this behavior. This can cause queries to hang or fail intermittently. + +:::