Understand what Hyperdrive accelerates

A Worker runs near the user. Your PostgreSQL or MySQL database sits in one region. That distance is the problem Hyperdrive solves, and it’s worth seeing exactly where the time goes.

Every request that opens a fresh connection pays for TCP, TLS, and authentication before it sends a single query. For Postgres, a cold connection looks like this:

TCP handshake            1+ round trip
TLS negotiation          1-2 round trips
Postgres auth exchange   2+ round trips
your actual query        1 round trip

Put the database in Virginia and the user in Sydney, and each round trip costs around 200 ms. Connection setup alone burns most of a second. The query you cared about is one round trip at the end.

Workers make this worse than a traditional server. There’s no long-lived process holding a warm connection between requests, so every request starts cold.

What Hyperdrive changes

Hyperdrive keeps a pool of connections close to the database and gives your Worker a nearby endpoint to talk to. The expensive setup happens once, near the database, and stays warm. Your driver connects to the closest Cloudflare data center over a fast path, borrows a pooled connection, and pays roughly one round trip instead of seven.

It can also cache eligible reads. Repeated identical queries may never reach the origin at all. A later lesson covers when that’s safe.

What it doesn’t change

Hyperdrive does not fix slow SQL, missing indexes, or an overloaded database. A query that takes 900 ms to execute still takes 900 ms. Hyperdrive removes the connection tax, nothing more.

So before adding it, measure a direct connection. You want to know what you’re buying:

const start = performance.now()
const client = await connectDirectly(env.DATABASE_URL)
const connected = performance.now()

await client.query('select id, title from posts limit 20')
const queried = performance.now()

console.log(`connect: ${connected - start}ms, query: ${queried - connected}ms`)
// connect: 640ms, query: 45ms  <- connection-dominated: Hyperdrive helps
// connect: 90ms, query: 1200ms <- query-dominated: fix the SQL first

Split the time into connecting, querying, and returning the response. If connecting dominates, Hyperdrive will transform your latency. If querying dominates, you have a database problem, and the honest fix is an index or a better query.

Try this on your own database before you add Hyperdrive. Write the two numbers down. You’ll want them when you measure the difference afterwards.