Configuration

See README.md for overview.

Create Config

PostgreSQL:

# Basic
npx wrangler hyperdrive create my-db \\
  --connection-string="postgres://user:pass@host:5432/db"

# Custom cache
npx wrangler hyperdrive create my-db \\
  --connection-string="postgres://..." \\
  --max-age=120 --swr=30

# No cache
npx wrangler hyperdrive create my-db \\
  --connection-string="postgres://..." \\
  --caching-disabled=true

MySQL:

npx wrangler hyperdrive create my-db \\
  --connection-string="mysql://user:pass@host:3306/db"

wrangler.jsonc

{
  "compatibility_date": "2025-01-01", // Use latest for new projects
  "compatibility_flags": ["nodejs_compat"],
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<HYPERDRIVE_ID>",
      "localConnectionString": "postgres://user:pass@localhost:5432/dev"
    }
  ]
}

Generate TypeScript types: Run npx wrangler types to auto-generate worker-configuration.d.ts from your wrangler.jsonc.

Multiple configs:

{
  "hyperdrive": [
    {"binding": "HYPERDRIVE_CACHED", "id": ""},
    {"binding": "HYPERDRIVE_NO_CACHE", "id": ""}
  ]
}

Management

npx wrangler hyperdrive list
npx wrangler hyperdrive get 
npx wrangler hyperdrive update  --max-age=180
npx wrangler hyperdrive delete 

Config Options

Hyperdrive create/update CLI flags:

Smart Placement Integration

For Workers making multiple queries per request, enable Smart Placement to execute near your database:

{
  "compatibility_date": "2025-01-01",
  "compatibility_flags": ["nodejs_compat"],
  "placement": {
    "mode": "smart"
  },
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<HYPERDRIVE_ID>"
    }
  ]
}

Benefits: Multi-query Workers run closer to DB, reducing round-trip latency. See patterns.md for examples.

Private DB via Tunnel

Worker → Hyperdrive → Access → Tunnel → Private Network → DB

Setup:

# 1. Create tunnel
cloudflared tunnel create my-db-tunnel

# 2. Configure hostname in Zero Trust dashboard
#    Domain: db-tunnel.example.com
#    Service: TCP -> localhost:5432

# 3. Create service token (Zero Trust > Service Auth)
#    Save Client ID/Secret

# 4. Create Access app (db-tunnel.example.com)
#    Policy: Service Auth token from step 3

# 5. Create Hyperdrive
npx wrangler hyperdrive create my-private-db \\
  --host=db-tunnel.example.com \\
  --user=dbuser --password=dbpass --database=prod \\
  --access-client-id= --access-client-secret=

⚠️ Don't specify --port with Tunnel - port configured in tunnel service settings.

Local Dev

Option 1: Local (RECOMMENDED):

# Env var (takes precedence)

npx wrangler dev

# wrangler.jsonc
{"hyperdrive": [{"binding": "HYPERDRIVE", "localConnectionString": "postgres://..."}]}

Remote DB locally:

# PostgreSQL

# MySQL

Option 2: Remote execution:

npx wrangler dev --remote  # Uses deployed config, affects production

See api.md, patterns.md, gotchas.md.