Initial commit

2025-11-30 08:24:16 +08:00
commit cfc6c441b5
22 changed files with 5629 additions and 0 deletions
--- a/references/wrangler-commands.md
+++ b/references/wrangler-commands.md
@@ -0,0 +1,488 @@
+# 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
+
+```bash
+npx wrangler hyperdrive create <name> \
+  --connection-string="postgres://user:password@host:port/database"
+```
+
+**Example**:
+```bash
+npx wrangler hyperdrive create my-postgres-db \
+  --connection-string="postgres://myuser:mypass@db.example.com:5432/mydb"
+```
+
+### MySQL
+
+```bash
+npx wrangler hyperdrive create <name> \
+  --connection-string="mysql://user:password@host:port/database"
+```
+
+**Example**:
+```bash
+npx wrangler hyperdrive create my-mysql-db \
+  --connection-string="mysql://myuser:mypass@db.example.com:3306/mydb"
+```
+
+### With SSL Mode (PostgreSQL)
+
+```bash
+npx wrangler hyperdrive create my-db \
+  --connection-string="postgres://..." \
+  --sslmode require  # or verify-ca, verify-full
+```
+
+### With Server CA Certificate
+
+```bash
+# 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)
+
+```bash
+# 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.
+
+```bash
+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.
+
+```bash
+npx wrangler hyperdrive get <hyperdrive-id>
+```
+
+**Example**:
+```bash
+npx wrangler hyperdrive get a76a99bc-7901-48c9-9c15-c4b11b559606
+```
+
+**Output**:
+```json
+{
+  "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
+
+```bash
+npx wrangler hyperdrive update <hyperdrive-id> \
+  --connection-string="postgres://newuser:newpass@newhost:5432/newdb"
+```
+
+### Update Name
+
+```bash
+npx wrangler hyperdrive update <hyperdrive-id> \
+  --name="my-renamed-db"
+```
+
+### Disable Caching
+
+```bash
+npx wrangler hyperdrive update <hyperdrive-id> \
+  --caching-disabled
+```
+
+### Enable Caching
+
+```bash
+npx wrangler hyperdrive update <hyperdrive-id> \
+  --caching-disabled=false
+```
+
+**Use Case - Credential Rotation**:
+```bash
+# 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.
+
+```bash
+npx wrangler hyperdrive delete <hyperdrive-id>
+```
+
+**Example**:
+```bash
+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.
+
+```bash
+npx wrangler cert upload certificate-authority \
+  --ca-cert <path-to-ca-cert.pem> \
+  --name <custom-name>
+```
+
+**Example**:
+```bash
+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.
+
+```bash
+npx wrangler cert upload mtls-certificate \
+  --cert <path-to-client-cert.pem> \
+  --key <path-to-private-key.pem> \
+  --name <custom-name>
+```
+
+**Example**:
+```bash
+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**:
+```bash
+# 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
+
+```bash
+# 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**
+```bash
+# 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)**
+```bash
+# 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
+
+```bash
+# 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.
+
+```bash
+# 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
+
+```bash
+# Check config exists and view details
+npx wrangler hyperdrive get <hyperdrive-id>
+
+# List all configs
+npx wrangler hyperdrive list
+```
+
+### Check Wrangler Version
+
+```bash
+# 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**:
+```bash
+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**:
+```bash
+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:
+   ```bash
+   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](https://developers.cloudflare.com/hyperdrive/reference/wrangler-commands/)
+- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)
+- [Gradual Deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/)