scribase
Fix guide

Neon's serverless driver keeps timing out in your edge function

Neon's own docs recommend HTTP as the default for this driver and reserve WebSockets for a specific case — interactive transactions. A timeout in an edge or serverless function is usually either the wrong mode for the job, or a WebSocket connection trying to live longer than the one request that opened it.

Last checked November 18, 2026.

HTTP vs. WebSocket: when each is right

Neon's docs are explicit about the default: "Use the driver over HTTP by default. The neon() function sends each query as an HTTP fetch request, which is the fastest option for single queries" and "non-interactive transactions" (several statements sent as one request). Switch to "WebSockets, with the Pool or Client constructors, only if you need interactive transactions, sessions, or compatibility with node-postgres."

The constraint that catches people: in an edge runtime, a WebSocket connection "can't outlive a single request" — opening one, doing work across multiple async steps, and leaving it open past the handler's return is the timeout pattern, not a flaky network.

Sources: Neon: Serverless driver

The fix

  • For a single query or a batch of non-interactive statements, use the HTTP neon() function — it is the documented default and the fastest option, with no connection lifecycle to manage at all.
  • Only reach for the WebSocket Pool/Client constructors when a transaction genuinely needs interactive session state (e.g. a multi-statement transaction that depends on earlier results) or when migrating an existing node-postgres codebase as-is.
  • If using WebSockets in an edge function, connect, run the transaction, and close the connection within the same request handler — never hold it open across handler invocations or background work that outlives the response.
  • Configure a fetch timeout explicitly if the default is too long or too short for the function's own platform timeout, rather than letting the platform kill the request mid-query with no clear error.

Sources: Neon: Serverless driver

Scribase has the same HTTP path

Scribase's own HTTP-based data API is the same shape of answer to this problem: a serverless/edge function can issue one query over a plain fetch request with no connection object to open, hold, or accidentally leak across invocations — the same reason Neon recommends its own HTTP driver as the default rather than WebSockets for this exact environment.

Sources: Scribase pricing

FAQ

Questions people ask

Should I default to HTTP or WebSocket with the Neon serverless driver?

HTTP, per Neon's own guidance — the neon() function is the documented default for single queries and non-interactive transactions, and WebSockets are reserved for interactive sessions or node-postgres compatibility.

Why does my WebSocket connection time out specifically in an edge function?

Because, per Neon's docs, a WebSocket connection can't outlive a single request in an edge runtime — holding it open past the handler's return (for example across an awaited background task) is the timeout.

Does switching to HTTP fix a multi-statement transaction?

Only if the statements do not depend on interactive session state between them — the HTTP mode supports non-interactive transactions sent as one request, but a transaction that needs to read a result mid-way and branch needs the WebSocket/session mode instead.

Is this specific to edge runtimes, or does it happen in regular serverless functions too?

The 'WebSocket can't outlive a request' constraint is specifically an edge-runtime limitation per Neon's docs; a traditional (non-edge) serverless function has more flexibility, though the HTTP mode is still the faster default for single queries either way.