cloudflare-hyperdrive

Cloudflare Hyperdrive

Status: Production Ready ✅ | Last Verified: 2025-11-18

---

What Is Hyperdrive?

Connect Workers to existing PostgreSQL/MySQL databases:

• Global connection pooling
• Query caching
• Reduced latency
• Works with node-postgres, postgres.js, mysql2

---

Quick Start (5 Minutes)

1. Create Hyperdrive Config

bunx wrangler hyperdrive create my-db \
  --connection-string="postgres://user:pass@host:5432/database"

Save the id!

2. Configure Binding

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23",
  "compatibility_flags": ["nodejs_compat"],  // REQUIRED!
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<ID_FROM_STEP_1>"
    }
  ]
}

3. Install Driver

bun add pg  # or postgres, or mysql2

4. Query Database

import { Client } from 'pg';

export default {
  async fetch(request, env, ctx) {
    const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
    await client.connect();

    const result = await client.query('SELECT * FROM users LIMIT 10');
    await client.end();

    return Response.json(result.rows);
  }
};

Load references/setup-guide.md for complete walkthrough.

---

Critical Rules

Always Do ✅

1. Enable nodejs_compat flag (required!)
2. Use env.HYPERDRIVE.connectionString (not original DB string)
3. Close connections after queries
4. Handle errors explicitly
5. Use connection pooling (built-in)
6. Test locally with wrangler dev
7. Monitor query performance
8. Use prepared statements
9. Enable query caching (automatic)
10. Secure connection strings (use secrets)

Never Do ❌

1. Never skip nodejs_compat (drivers won't work)
2. Never use original DB connection string in Workers
3. Never leave connections open (pool exhaustion)
4. Never skip error handling (DB can fail)
5. Never hardcode credentials in code
6. Never exceed connection limits
7. Never use eval/Function (blocked in Workers)
8. Never skip TLS for production DBs
9. Never use blocking queries (Worker timeout)
10. Never expose DB errors to users