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 credenti