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

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

Save the `id`!

### 2. Configure Binding

```jsonc
{
  "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

```bash
bun add pg  # or postgres, or mysql2
```

### 4. Query Database

```typescript
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)

```typescript
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)

```typescript
import postgres from 'postgres';

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

### MySQL

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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** (`references/`):
- `setup-guide.md` - Complete setup walkthrough (create config, bind, query)
- `connection-pooling.md` - Connection pool configuration and best practices
- `query-caching.md` - Query caching strategies and optimization
- `drizzle-integration.md` - Drizzle ORM integration patterns
- `prisma-integration.md` - Prisma ORM integration patterns
- `supported-databases.md` - Complete list of supported PostgreSQL and MySQL providers
- `tls-ssl-setup.md` - TLS/SSL configuration for secure connections
- `troubleshooting.md` - Common issues and solutions
- `wrangler-commands.md` - Complete wrangler CLI commands for Hyperdrive

**Templates** (`templates/`):
- `postgres-basic.ts` - Basic PostgreSQL with node-postgres
- `postgres-js.ts` - PostgreSQL with postgres.js driver
- `postgres-pool.ts` - PostgreSQL with connection pooling
- `mysql2-basic.ts` - MySQL with mysql2 driver
- `drizzle-postgres.ts` - Drizzle ORM with PostgreSQL
- `drizzle-mysql.