1# Hyperdrive
2 
3Accelerates database queries from Workers via connection pooling, edge setup, query caching.
4 
5## Key Features
6 
7- **Connection Pooling**: Persistent connections eliminate TCP/TLS/auth handshakes (~7 round-trips)
8- **Edge Setup**: Connection negotiation at edge, pooling near origin
9- **Query Caching**: Auto-cache non-mutating queries (default 60s TTL)
10- **Support**: PostgreSQL, MySQL + compatibles (CockroachDB, Timescale, PlanetScale, Neon, Supabase)
11 
12## Architecture
13 
14```
15Worker → Edge (setup) → Pool (near DB) → Origin
16         ↓ cached reads
17         Cache
18```
19 
20## Quick Start
21 
22```bash
23# Create config
24npx wrangler hyperdrive create my-db \
25  --connection-string="postgres://user:pass@host:5432/db"
26 
27# wrangler.jsonc
28{
29  "compatibility_flags": ["nodejs_compat"],
30  "hyperdrive": [{"binding": "HYPERDRIVE", "id": "<ID>"}]
31}
32```
33 
34```typescript
35import { Client } from "pg";
36 
37export default {
38  async fetch(req: Request, env: Env): Promise<Response> {
39    const client = new Client({
40      connectionString: env.HYPERDRIVE.connectionString,
41    });
42    await client.connect();
43    const result = await client.query("SELECT * FROM users WHERE id = $1", [123]);
44    await client.end();
45    return Response.json(result.rows);
46  },
47};
48```
49 
50## When to Use
51 
52✅ Global access to single-region DBs, high read ratios, popular queries, connection-heavy loads
53❌ Write-heavy, real-time data (<1s), single-region apps close to DB
54 
55**💡 Pair with Smart Placement** for Workers making multiple queries - executes near DB to minimize latency.
56 
57## Driver Choice
58 
59| Driver | Use When | Notes |
60|--------|----------|-------|
61| **pg** (recommended) | General use, TypeScript, ecosystem compatibility | Stable, widely used, works with most ORMs |
62| **postgres.js** | Advanced features, template literals, streaming | Lighter than pg, `prepare: true` is default |
63| **mysql2** | MySQL/MariaDB/PlanetScale | MySQL only, less mature support |
64 
65## Reading Order
66 
67| New to Hyperdrive | Implementing | Troubleshooting |
68|-------------------|--------------|-----------------|
69| 1. README (this) | 1. [configuration.md](./configuration.md) | 1. [gotchas.md](./gotchas.md) |
70| 2. [configuration.md](./configuration.md) | 2. [api.md](./api.md) | 2. [patterns.md](./patterns.md) |
71| 3. [api.md](./api.md) | 3. [patterns.md](./patterns.md) | 3. [api.md](./api.md) |
72 
73## In This Reference
74- [configuration.md](./configuration.md) - Setup, wrangler config, Smart Placement
75- [api.md](./api.md) - Binding APIs, query patterns, driver usage
76- [patterns.md](./patterns.md) - Use cases, ORMs, multi-query optimization
77- [gotchas.md](./gotchas.md) - Limits, troubleshooting, connection management
78 
79## See Also
80- [smart-placement](../smart-placement/) - Optimize multi-query Workers near databases
81- [d1](../d1/) - Serverless SQLite alternative for edge-native apps
82- [workers](../workers/) - Worker runtime with database bindings
83