Connect a Worker to existing Postgres via Hyperdrive

You have a regional Postgres already running — maybe on Neon, Supabase, AWS RDS, or your own server. It lives in one place. Your Workers, on the other hand, run in hundreds of cities. This guide wires a Worker to that database through Hyperdrive, so every request reuses warm connections and reads from cache instead of paying full latency each time.

Hyperdrive sits in the middle as a connection pooler plus query cache. Your code still uses a normal Postgres driver — the only change is that it connects to env.HYPERDRIVE.connectionString instead of your database's real URL.

The diagram below shows the same workload twice. The top half connects directly and rebuilds a connection on every request. The bottom half goes through Hyperdrive and reuses a warm, pooled link — often answering straight from cache.

Five steps: create a Hyperdrive config pointing at your DB, add the binding to wrangler.toml, install a Postgres driver, query through env.HYPERDRIVE.connectionString, and deploy.

1. Create a Hyperdrive config

   Hand Hyperdrive your existing connection string. Wrangler prints an id — copy it for the next step.

   bashcontent_copyCopy

   npx wrangler hyperdrive create my-postgres \
     --connection-string="postgres://user:password@db.example.com:5432/appdb"

2. Add the [[hyperdrive]] binding

   Paste the id into wrangler.toml. The nodejs_compat flag is required, because Postgres drivers depend on Node APIs.

   tomlcontent_copyCopy

   name = "my-worker"
   main = "src/index.js"
   compatibility_date = "2024-09-23"
   compatibility_flags = ["nodejs_compat"]
   
   [[hyperdrive]]
   binding = "HYPERDRIVE"
   id = "<paste-the-id-from-step-1>"

3. Install a Postgres driver

   We use postgres.js here; the node-postgres pg package works too.

   bashcontent_copyCopy

   npm i postgres

4. Query through Hyperdrive

   Connect to env.HYPERDRIVE.connectionString — never the real DB URL. Keep a small per-isolate pool and close it in the background.

   jscontent_copyCopy

   import postgres from "postgres";
   
   export default {
     async fetch(request, env, ctx) {
       // Connect to Hyperdrive, not the database directly
       const sql = postgres(env.HYPERDRIVE.connectionString, {
         max: 5,            // small pool per Worker isolate
         fetch_types: false // skip an extra round-trip
       });
   
       try {
         const products = await sql`SELECT id, name, price FROM products LIMIT 10`;
         // Close in the background so it does not delay the response
         ctx.waitUntil(sql.end());
         return Response.json(products);
       } catch (err) {
         console.error(err);
         return Response.json({ error: String(err) }, { status: 500 });
       }
     }
   };

5. Deploy

   Publish the Worker. Queries now flow through the pooled, cached fast lane.

   bashcontent_copyCopy

   npx wrangler deploy

Reads and writes, safely

// Parameterized values are sent separately, never string-concatenated
const id = 42;
const rows = await sql`SELECT id, name FROM products WHERE id = ${id}`;

// Writes (INSERT/UPDATE/DELETE) are never cached — they always hit Postgres
await sql`INSERT INTO views (product_id) VALUES (${id})`;

• Without compatibility_flags = ["nodejs_compat"] and a recent compatibility_date, the Postgres driver fails to load.
• Only read-only SELECTs are cached; INSERT/UPDATE/DELETE always reach Postgres.
• Queries using NOW(), RANDOM(), or CURRENT_DATE are treated as uncacheable — even just naming one in a SQL comment disables caching for that query.
• Always close with ctx.waitUntil(sql.end()) so cleanup never delays the response.
• Keep the per-isolate pool small (e.g. max: 5); Hyperdrive multiplexes across them anyway.
• Works with Postgres and Postgres-compatibles (Neon, Supabase, RDS, CockroachDB, Timescale) — and MySQL too.
• Need a Cloudflare-native SQL database instead of bringing your own? See D1.