Neon on Cloudflare Workers: Hyperdrive first, serverless driver second

TL;DR

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. With Hyperdrive, use native PostgreSQL drivers like node-postgres or Postgres.js, not the Neon serverless driver.

Steps

1. 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.
2. 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.
3. Create a Hyperdrive config pointing at your Neon database.
4. Bind it to your Worker (wrangler.toml / dashboard bindings).
5. Connect with pg using the Hyperdrive connection string from the binding.
6. 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.

When to use

You are seeing this: Workers have no TCP sockets either, so naive pg usage fails. Use this skill when you run into "Neon on Cloudflare Workers: Hyperdrive first, serverless driver second".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

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.