1# Configuration
2 
3See [README.md](./README.md) for overview.
4 
5## Create Config
6 
7**PostgreSQL:**
8```bash
9# Basic
10npx wrangler hyperdrive create my-db \
11  --connection-string="postgres://user:pass@host:5432/db"
12 
13# Custom cache
14npx wrangler hyperdrive create my-db \
15  --connection-string="postgres://..." \
16  --max-age=120 --swr=30
17 
18# No cache
19npx wrangler hyperdrive create my-db \
20  --connection-string="postgres://..." \
21  --caching-disabled=true
22```
23 
24**MySQL:**
25```bash
26npx wrangler hyperdrive create my-db \
27  --connection-string="mysql://user:pass@host:3306/db"
28```
29 
30## wrangler.jsonc
31 
32```jsonc
33{
34  "compatibility_date": "2025-01-01", // Use latest for new projects
35  "compatibility_flags": ["nodejs_compat"],
36  "hyperdrive": [
37    {
38      "binding": "HYPERDRIVE",
39      "id": "<HYPERDRIVE_ID>",
40      "localConnectionString": "postgres://user:pass@localhost:5432/dev"
41    }
42  ]
43}
44```
45 
46**Generate TypeScript types:** Run `npx wrangler types` to auto-generate `worker-configuration.d.ts` from your wrangler.jsonc.
47 
48**Multiple configs:**
49```jsonc
50{
51  "hyperdrive": [
52    {"binding": "HYPERDRIVE_CACHED", "id": "<ID1>"},
53    {"binding": "HYPERDRIVE_NO_CACHE", "id": "<ID2>"}
54  ]
55}
56```
57 
58## Management
59 
60```bash
61npx wrangler hyperdrive list
62npx wrangler hyperdrive get <ID>
63npx wrangler hyperdrive update <ID> --max-age=180
64npx wrangler hyperdrive delete <ID>
65```
66 
67## Config Options
68 
69Hyperdrive create/update CLI flags:
70 
71| Option | Default | Notes |
72|--------|---------|-------|
73| `--caching-disabled` | `false` | Disable caching |
74| `--max-age` | `60` | Cache TTL (max 3600s) |
75| `--swr` | `15` | Stale-while-revalidate |
76| `--origin-connection-limit` | 20/100 | Free/paid |
77| `--access-client-id` | - | Tunnel auth |
78| `--access-client-secret` | - | Tunnel auth |
79| `--sslmode` | `require` | PostgreSQL only |
80 
81## Smart Placement Integration
82 
83For Workers making **multiple queries** per request, enable Smart Placement to execute near your database:
84 
85```jsonc
86{
87  "compatibility_date": "2025-01-01",
88  "compatibility_flags": ["nodejs_compat"],
89  "placement": {
90    "mode": "smart"
91  },
92  "hyperdrive": [
93    {
94      "binding": "HYPERDRIVE",
95      "id": "<HYPERDRIVE_ID>"
96    }
97  ]
98}
99```
100 
101**Benefits:** Multi-query Workers run closer to DB, reducing round-trip latency. See [patterns.md](./patterns.md) for examples.
102 
103## Private DB via Tunnel
104 
105```
106Worker → Hyperdrive → Access → Tunnel → Private Network → DB
107```
108 
109**Setup:**
110```bash
111# 1. Create tunnel
112cloudflared tunnel create my-db-tunnel
113 
114# 2. Configure hostname in Zero Trust dashboard
115#    Domain: db-tunnel.example.com
116#    Service: TCP -> localhost:5432
117 
118# 3. Create service token (Zero Trust > Service Auth)
119#    Save Client ID/Secret
120 
121# 4. Create Access app (db-tunnel.example.com)
122#    Policy: Service Auth token from step 3
123 
124# 5. Create Hyperdrive
125npx wrangler hyperdrive create my-private-db \
126  --host=db-tunnel.example.com \
127  --user=dbuser --password=dbpass --database=prod \
128  --access-client-id=<ID> --access-client-secret=<SECRET>
129```
130 
131**⚠️ Don't specify `--port` with Tunnel** - port configured in tunnel service settings.
132 
133## Local Dev
134 
135**Option 1: Local (RECOMMENDED):**
136```bash
137# Env var (takes precedence)
138export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:pass@localhost:5432/dev"
139npx wrangler dev
140 
141# wrangler.jsonc
142{"hyperdrive": [{"binding": "HYPERDRIVE", "localConnectionString": "postgres://..."}]}
143```
144 
145**Remote DB locally:**
146```bash
147# PostgreSQL
148export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:pass@remote:5432/db?sslmode=require"
149 
150# MySQL
151export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="mysql://user:pass@remote:3306/db?sslMode=REQUIRED"
152```
153 
154**Option 2: Remote execution:**
155```bash
156npx wrangler dev --remote  # Uses deployed config, affects production
157```
158 
159See [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md).
160