Neon on Cloudflare Workers: Hyperdrive first, serverless driver second

Neon on Cloudflare Workers: pick the right connection path

The trap

Workers have no TCP sockets either, so naive pg usage fails. There are two working paths and they are not interchangeable: Hyperdrive (Cloudflare's pooling service) with a native driver, or the Neon serverless driver over HTTP/WebSockets. Mixing them (serverless driver through Hyperdrive) gets you double pooling and weird behavior.

The rule (current docs)

Neon's Cloudflare Workers guide recommends Hyperdrive as the approach: it does connection setup and pooling across Cloudflare's network with the lowest latency. With Hyperdrive, use native PostgreSQL drivers like node-postgres or Postgres.js, not the Neon serverless driver.

1. Create a Hyperdrive config pointing at your Neon database.
2. Bind it to your Worker (wrangler.toml / dashboard bindings).
3. Connect with pg using the Hyperdrive connection string from the binding.

The fallback path

Without Hyperdrive, use @neondatabase/serverless over HTTP (neon() one-shot client) or WebSockets. Same Edge rule as Vercel applies: Pool/Client objects cannot outlive a single request, so create, use, and close them inside the handler.

Checklist

• Hyperdrive + pg (or Postgres.js) is the recommended path.
• No Hyperdrive -> @neondatabase/serverless, HTTP for one-shots.
• Never put the serverless driver behind Hyperdrive.
• The old ws-proxy workaround from community posts is superseded; follow the current guide.

Neon's Cloudflare Workers guide (verified live 2026-09-26) recommends Hyperdrive with native PostgreSQL drivers like node-postgres instead of the Neon serverless driver; the serverless driver remains the fallback over HTTP or WebSockets, with the single-request lifetime rule for Pool/Client.