/cloudflare-hyperdrive

name: cloudflare-hyperdrive
description: "Cloudflare Hyperdrive for Workers-to-database connections with pooling and caching. Use for PostgreSQL/MySQL, Drizzle/Prisma, or encountering pool errors, TLS issues, connection refused."
license: MIT
metadata:
  version: "2.0.0"
  last_verified: "2025-11-18"
  production_tested: true
  token_savings: "~58%"
  errors_prevented: 6
  templates_included: 0
  references_included: 1
  keywords:
    - hyperdrive
    - cloudflare hyperdrive
    - workers hyperdrive
    - postgres workers
    - mysql workers
    - connection pooling
    - query caching
    - node-postgres
    - pg
    - postgres.js
    - mysql2
    - drizzle hyperdrive
    - prisma hyperdrive
    - workers rds
    - workers aurora
    - workers neon
    - workers supabase
    - database acceleration
    - hybrid architecture
    - cloudflare tunnel database
    - wrangler hyperdrive
    - hyperdrive bindings
    - local development 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

---

Database Drivers

PostgreSQL (node-postgres)

import { Client } from 'pg';

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
const result = await client.query('SELECT * FROM users');
await client.end();

PostgreSQL (postgres.js)

import postgres from 'postgres';

const sql = postgres(env.HYPERDRIVE.connectionString);
const users = await sql`SELECT * FROM users`;

MySQL

import mysql from 'mysql2/promise';

const connection = await mysql.createConnection(env.HYPERDRIVE.connectionString);
const [rows] = await connection.execute('SELECT * FROM users');
await connection.end();

---

With Drizzle ORM

import { drizzle } from 'drizzle-orm/node-postgres';
import { Client } from 'pg';

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();

const db = drizzle(client);
const users = await db.select().from(usersTable);

await client.end();

---

Common Use Cases

Use Case 1: Read-Only Queries

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

    const users = await client.query('SELECT * FROM users WHERE active = true');
    await client.end();

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

Use Case 2: Parameterized Queries

const userId = new URL(request.url).searchParams.get('id');

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();

const result = await client.query(
  'SELECT * FROM users WHERE id = $1',
  [userId]
);

await client.end();

Use Case 3: Transactions

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();

try {
  await client.query('BEGIN');
  await client.query('UPDATE accounts SET balance = balance - 100 WHERE id = $1', [1]);
  await client.query('UPDATE accounts SET balance = balance + 100 WHERE id = $1', [2]);
  await client.query('COMMIT');
} catch (e) {
  await client.query('ROLLBACK');
  throw e;
} finally {
  await client.end();
}

---

Supported Databases

**PostgreSQL:**

• Amazon RDS
• Amazon Aurora
• Neon
• Supabase
• Railway
• Render
• DigitalOcean
• Any PostgreSQL 11+

**MySQL:**

• Amazon RDS
• Amazon Aurora
• PlanetScale
• Any MySQL 5.7+

---

Official Documentation

• **Hyperdrive Overview**: https://developers.cloudflare.com/hyperdrive/
• **Get Started**: https://developers.cloudflare.com/hyperdrive/get-started/
• **Configuration**: https://developers.cloudflare.com/hyperdrive/configuration/

---

Bundled Resources

**References