gh-jezweb-claude-skills-skills-cloudflare-hyperdrive/references/wrangler-commands.md

Hyperdrive Wrangler Commands Reference

Complete CLI reference for managing Hyperdrive configurations with Wrangler.

Minimum Wrangler Version: 3.11.0+

---

Create Hyperdrive Configuration

Create a new Hyperdrive configuration that connects to a database.

PostgreSQL

npx wrangler hyperdrive create <name> \
  --connection-string="postgres://user:password@host:port/database"

Example:

npx wrangler hyperdrive create my-postgres-db \
  --connection-string="postgres://myuser:mypass@db.example.com:5432/mydb"

MySQL

npx wrangler hyperdrive create <name> \
  --connection-string="mysql://user:password@host:port/database"

Example:

npx wrangler hyperdrive create my-mysql-db \
  --connection-string="mysql://myuser:mypass@db.example.com:3306/mydb"

With SSL Mode (PostgreSQL)

npx wrangler hyperdrive create my-db \
  --connection-string="postgres://..." \
  --sslmode require  # or verify-ca, verify-full

With Server CA Certificate

# First, upload CA certificate
npx wrangler cert upload certificate-authority \
  --ca-cert root-ca.pem \
  --name my-ca-cert

# Then create Hyperdrive with CA
npx wrangler hyperdrive create my-db \
  --connection-string="postgres://..." \
  --ca-certificate-id <CA_CERT_ID> \
  --sslmode verify-full

With Client Certificates (mTLS)

# First, upload client certificate + key
npx wrangler cert upload mtls-certificate \
  --cert client-cert.pem \
  --key client-key.pem \
  --name my-client-cert

# Then create Hyperdrive with client cert
npx wrangler hyperdrive create my-db \
  --connection-string="postgres://..." \
  --mtls-certificate-id <CERT_PAIR_ID>

Output:

✅ Successfully created Hyperdrive configuration

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "a76a99bc-7901-48c9-9c15-c4b11b559606"

---

List Hyperdrive Configurations

List all Hyperdrive configurations in your account.

npx wrangler hyperdrive list

Output:

┌──────────────────────────────────────┬─────────────────┬────────────────┐
│ id                                   │ name            │ database       │
├──────────────────────────────────────┼─────────────────┼────────────────┤
│ a76a99bc-7901-48c9-9c15-c4b11b559606 │ my-postgres-db  │ PostgreSQL     │
│ b8c12345-6789-12ab-cdef-012345678901 │ my-mysql-db     │ MySQL          │
└──────────────────────────────────────┴─────────────────┴────────────────┘

---

Get Hyperdrive Configuration Details

Get details of a specific Hyperdrive configuration.

npx wrangler hyperdrive get <hyperdrive-id>

Example:

npx wrangler hyperdrive get a76a99bc-7901-48c9-9c15-c4b11b559606

Output:

{
  "id": "a76a99bc-7901-48c9-9c15-c4b11b559606",
  "name": "my-postgres-db",
  "origin": {
    "host": "db.example.com",
    "port": 5432,
    "database": "mydb",
    "user": "myuser",
    "scheme": "postgres"
  },
  "caching": {
    "disabled": false
  }
}

Note: Password is never returned for security reasons.

---

Update Hyperdrive Configuration

Update connection string or other settings of an existing configuration.

Update Connection String

npx wrangler hyperdrive update <hyperdrive-id> \
  --connection-string="postgres://newuser:newpass@newhost:5432/newdb"

Update Name

npx wrangler hyperdrive update <hyperdrive-id> \
  --name="my-renamed-db"

Disable Caching

npx wrangler hyperdrive update <hyperdrive-id> \
  --caching-disabled

Enable Caching

npx wrangler hyperdrive update <hyperdrive-id> \
  --caching-disabled=false

Use Case - Credential Rotation:

# Update with new password
npx wrangler hyperdrive update a76a99bc-7901-48c9-9c15-c4b11b559606 \
  --connection-string="postgres://user:new_password@host:5432/db"

---

Delete Hyperdrive Configuration

Delete a Hyperdrive configuration.

npx wrangler hyperdrive delete <hyperdrive-id>

Example:

npx wrangler hyperdrive delete a76a99bc-7901-48c9-9c15-c4b11b559606

Confirmation Prompt:

? Are you sure you want to delete Hyperdrive configuration a76a99bc-7901-48c9-9c15-c4b11b559606? › (y/N)

Warning: This action cannot be undone. Workers using this configuration will fail until updated.

---

Certificate Management

Upload CA Certificate (Server Certificate)

Upload a certificate authority (CA) certificate for verify-ca or verify-full SSL modes.

npx wrangler cert upload certificate-authority \
  --ca-cert <path-to-ca-cert.pem> \
  --name <custom-name>

Example:

npx wrangler cert upload certificate-authority \
  --ca-cert /path/to/root-ca.pem \
  --name aws-rds-ca-2024

Output:

✅ Uploaded CA Certificate aws-rds-ca-2024
ID: ca-12345678-1234-1234-1234-123456789012

Important: You must use region-specific CA certificates, not global bundles containing multiple CAs.

---

Upload Client Certificate (mTLS)

Upload client certificate and private key pair for mutual TLS authentication.

npx wrangler cert upload mtls-certificate \
  --cert <path-to-client-cert.pem> \
  --key <path-to-private-key.pem> \
  --name <custom-name>

Example:

npx wrangler cert upload mtls-certificate \
  --cert /path/to/client-cert.pem \
  --key /path/to/client-key.pem \
  --name my-client-cert

Output:

✅ Uploaded client certificate my-client-cert
ID: mtls-87654321-4321-4321-4321-210987654321

---

Connection String Formats

PostgreSQL

Basic:

postgres://username:password@hostname:port/database

With SSL Mode:

postgres://username:password@hostname:port/database?sslmode=require

With Special Characters in Password:

# Password: p@ssw$rd
# URL-encoded: p%40ssw%24rd
postgres://user:p%40ssw%24rd@host:5432/database

URL Encoding Reference:

• @ → %40
• # → %23
• $ → %24
• % → %25
• & → %26
• + → %2B
• / → %2F

---

MySQL

Basic:

mysql://username:password@hostname:port/database

Example:

mysql://admin:mypass123@mysql-prod.example.com:3306/app_db

---

Workflow Examples

Complete Setup Workflow

# 1. Create Hyperdrive configuration
npx wrangler hyperdrive create my-database \
  --connection-string="postgres://user:pass@host:5432/db"

# Output: id = a76a99bc-7901-48c9-9c15-c4b11b559606

# 2. Add to wrangler.jsonc
cat >> wrangler.jsonc <<EOF
{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "a76a99bc-7901-48c9-9c15-c4b11b559606"
    }
  ]
}
EOF

# 3. Deploy Worker
npx wrangler deploy

---

Credential Rotation Workflow

Option A: Update Existing Config

# Update with new credentials
npx wrangler hyperdrive update a76a99bc-7901-48c9-9c15-c4b11b559606 \
  --connection-string="postgres://user:NEW_PASSWORD@host:5432/db"

# Deploy (Workers automatically use new credentials)
npx wrangler deploy

Option B: Create New Config (Zero Downtime)

# 1. Create new config with new credentials
npx wrangler hyperdrive create my-database-v2 \
  --connection-string="postgres://user:NEW_PASSWORD@host:5432/db"

# Output: id = b8c12345-6789-12ab-cdef-012345678901

# 2. Update wrangler.jsonc with new ID
# 3. Deploy gradually with gradual deployments

# 4. Delete old config when migration complete
npx wrangler hyperdrive delete a76a99bc-7901-48c9-9c15-c4b11b559606

---

Multiple Database Workflow

# Create multiple Hyperdrive configs
npx wrangler hyperdrive create postgres-db \
  --connection-string="postgres://..."

npx wrangler hyperdrive create mysql-db \
  --connection-string="mysql://..."

# Configure in wrangler.jsonc
cat >> wrangler.jsonc <<EOF
{
  "hyperdrive": [
    {
      "binding": "POSTGRES_DB",
      "id": "<postgres-id>"
    },
    {
      "binding": "MYSQL_DB",
      "id": "<mysql-id>"
    }
  ]
}
EOF

---

Troubleshooting Commands

Test Connection

Hyperdrive tests the connection when creating/updating. If creation succeeds, connection works.

# This command will fail fast if connection doesn't work
npx wrangler hyperdrive create test-connection \
  --connection-string="postgres://user:pass@host:5432/db"

Verify Configuration

# Check config exists and view details
npx wrangler hyperdrive get <hyperdrive-id>

# List all configs
npx wrangler hyperdrive list

Check Wrangler Version

# Ensure you have wrangler 3.11.0+
npx wrangler --version

---

Common Errors

"Hyperdrive will attempt to connect to your database..."

Full message:

Hyperdrive will attempt to connect to your database with the provided
credentials to verify they are correct before creating a configuration.

This is an info message, not an error. Hyperdrive is testing the connection.

If connection fails, you'll see specific error (2008-2016). See troubleshooting.md for solutions.

---

"wrangler: command not found"

Cause: Wrangler not installed.

Solution:

npm install -g wrangler
# or use npx
npx wrangler@latest hyperdrive list

---

"Missing required argument: --connection-string"

Cause: Forgot to provide connection string when creating Hyperdrive.

Solution:

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

---

Best Practices

1. Use npx for consistent wrangler versions: npx wrangler hyperdrive ...
2. Store connection strings securely - Never commit to git
3. Use environment variables for sensitive data:

   export DB_PASSWORD="secret"
   npx wrangler hyperdrive create my-db \
     --connection-string="postgres://user:$DB_PASSWORD@host:5432/db"
   

4. Test locally first with localConnectionString before deploying
5. Use gradual deployments when rotating credentials
6. Document Hyperdrive IDs in your project README
7. Separate configs for staging and production

---

References

• Official Wrangler Commands Docs
• Wrangler Configuration
• Gradual Deployments