skip to content

With Hyperdrive, why should a Cloudflare Worker create a new database client in every request handler instead of keeping one global connection pool?

level: middleimportance: should knowfreq 28%

answer

  1. I/O belongs to one request
  2. seven round trips moved to the edge
  3. the pool lives near the database
  4. no client.end() needed

basics

~20 s

Workers cannot do I/O at module scope or reuse a socket from another request, so a global driver pool fails. Hyperdrive makes a per-request client cheap: the handshake finishes near the Worker and Hyperdrive reuses its own pooled connections near the database.

solid answer

~40 s

A Worker isolate serves many requests, but the runtime ties every socket to the request that opened it: connecting at module scope throws "Disallowed operation called within global scope", and touching an earlier request's socket throws "Cannot perform I/O on behalf of a different request". A driver-level `new Pool()` kept globally therefore leaves stale, failing connections. Hyperdrive moves pooling out of the isolate. The driver's TCP, TLS and authentication exchange, about seven round trips, completes against Hyperdrive in the same location as the Worker, and Hyperdrive sends the query over an already-open connection from a pool near the database. So you create a client per request, skip `client.end()`, and keep transactions short, because in Hyperdrive's transaction mode a connection is held until the transaction ends.

code

plaintext · 2 lines
plaintext
Uncaught Error: Disallowed operation called within global scope. Asynchronous I/O (ex: fetch() or connect()), setting a timeout, and generating random values are not allowed within global scope. To fix this error, perform this operation within a handler.
Cannot perform I/O on behalf of a different request. I/O objects (such as streams, request/response bodies, and others) created in the context of one request handler cannot be accessed from a different request's handler. This is a limitation of Cloudflare Workers which allows us to improve overall performance. (I/O type: Writable)

go deeper

for a junior

Remember the rule: build the database client inside the handler, every request, and let Hyperdrive worry about reuse.

for a middle

Explain the two runtime errors and how Hyperdrive splits connection setup between the edge and a pool near the database.

for a senior

Diagnose pool exhaustion from long transactions or Durable Objects holding clients, and explain why SET state disappears between queries.

for a principal

Set the team convention: per-request clients, no global pools, short transactions, and placement only when requests run several sequential queries.

## The rule the runtime enforces A **Cloudflare Worker** runs inside an isolate that is reused for many requests. Module-scope variables survive between requests, so on a traditional server you would build one connection pool at startup and share it. Workers forbid exactly that for I/O objects: - **No I/O at module scope.** Opening a socket while the script loads fails with `Disallowed operation called within global scope. Asynchronous I/O (ex: fetch() or connect()), setting a timeout, and generating random values are not allowed within global scope.` - **No I/O across requests.** A socket, stream or body created while handling one request cannot be used while handling another. The runtime throws `Cannot perform I/O on behalf of a different request.` A database client is a socket plus protocol state, so a client or a driver pool (`new Pool()`, `createPool()`) kept at module scope ends up holding connections that belong to finished requests. The drivers then surface errors such as node-postgres's `Client has already been connected. You cannot reuse a client.` or Postgres.js's `write CONNECTION_ENDED`. ## Why per-request clients are cheap with Hyperdrive Opening a fresh PostgreSQL connection over the internet costs roughly **seven round trips** before the first query: one for the TCP handshake, three for TLS negotiation and three for database authentication. From a Worker far from a regional database that is a large share of each request. Hyperdrive splits the path in two: 1. **Edge connection setup.** The driver performs its handshake against Hyperdrive in the same Cloudflare location as the Worker, so those round trips are short. 2. **One trip across regions.** Authentication is already done at the edge, so Hyperdrive forwards the query in a single round trip to its pool. 3. **A warm pooled connection.** The pool sits in one or more regions close to the origin database and reuses open connections; it opens a new one near the database only when none is free. 4. **Teardown that keeps the pool.** When the invocation ends, the Worker-side client is garbage collected and the edge connection is cleaned up, while Hyperdrive keeps the origin connection open for the next invocation. That is why the documented pattern is a new client in every `fetch`, `queue` or other handler, and no `client.end()`, `sql.end()` or `connection.end()` call. ## Transaction mode: what a pooled connection is lent for Hyperdrive's pool runs in **transaction mode**: a client gets one origin connection for a single query or for a whole `BEGIN` … `COMMIT` block, and the connection goes back to the pool afterwards. Three consequences matter in practice: | Behaviour | What it means for your code | | --- | --- | | Connection is `RESET` when returned | A `SET` outside a transaction does not carry to the next query; put it in the same query or transaction | | Held for the whole transaction | Long transactions, or slow calls made inside one, tie up origin connections | | One invocation may use several connections | Do not wrap unrelated queries in one transaction just to keep session state | When connections are held too long the pool runs dry and queries fail with `Failed to acquire a connection from the pool.` The pool also has a configured origin limit (about 20 connections per config on the Free plan and about 100 on Paid, soft limits), so the habit of short transactions matters more than it would against a local database. ## A special case: Durable Objects A Durable Object can keep state across requests, so it can hold a database client open for a long time. Each such client keeps an origin connection checked out of Hyperdrive's pool. Many objects doing that at once can exhaust the pool for every other Worker using the config, so close clients when idle and limit how many objects hold one. ## What this is not Hyperdrive does not make module-scope clients legal; the runtime rules above are the same with or without it. It also does not remove the cross-region round trip that each query needs. If a request makes several sequential queries, placing the Worker near the database is the separate tool for that latency.

  • Where do the round trips go when Hyperdrive has no free pooled connection?
    The driver's handshake still completes against Hyperdrive near the Worker. Hyperdrive then opens a new origin connection from a region close to the database, so the expensive TCP, TLS and authentication exchange happens over a short distance, and that connection stays in the pool for later invocations.
  • A Worker sets `SET statement_timeout = 5000` as its own query and then runs a slow report query through Hyperdrive. Why is the timeout ignored?
    In transaction mode each query outside a transaction may run on a different pooled connection, and a connection is `RESET` when it returns to the pool. Send the `SET` in the same query as the report, or run both inside one short `BEGIN` … `COMMIT` block.

  • Create one global node-postgres Pool so every request reuses the same connections.
  • Hyperdrive lets a Worker keep sockets open across requests.
  • Always call client.end() at the end of each request or the origin connection leaks.
  • Wrapping every request's queries in one transaction makes Hyperdrive faster.
  • With Hyperdrive, each query still pays the full TLS handshake to the distant database.