secondsky/claude-skills / plugins/cloudflare-hyperdrive/skills/cloudflare-hyperdrive
cloudflare-hyperdrive
VerifiedCloudflare Hyperdrive for Workers-to-database connections with pooling and caching. Use for PostgreSQL/MySQL, Drizzle/Prisma, or encountering pool errors, TLS issues, connection refused.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
| references/connection-pooling.md | markdown | 11.5 KB |
| references/drizzle-integration.md | markdown | 12.2 KB |
| references/prisma-integration.md | markdown | 12.8 KB |
| references/query-caching.md | markdown | 12.2 KB |
| references/setup-guide.md | markdown | 2.6 KB |
| references/supported-databases.md | markdown | 11.1 KB |
| references/tls-ssl-setup.md | markdown | 10.5 KB |
| references/troubleshooting.md | markdown | 13.3 KB |
| references/wrangler-commands.md | markdown | 10.6 KB |
| scripts/check-versions.shexecutable | script | 3.4 KB |
| templates/drizzle-mysql.ts | script | 2.2 KB |
| templates/drizzle-postgres.ts | script | 2.1 KB |
| templates/local-dev-setup.shexecutable | script | 2.4 KB |
| templates/mysql2-basic.ts | script | 2.0 KB |
| templates/postgres-basic.ts | script | 1.7 KB |
| templates/postgres-js.ts | script | 2.6 KB |
| templates/postgres-pool.ts | script | 2.4 KB |
| templates/prisma-postgres.ts | script | 3.3 KB |
| templates/wrangler-hyperdrive-config.jsonc | other | 1.0 KB |
SKILL.md
View on GitHub---
name: cloudflare-hyperdrive
description: "Cloudflare Hyperdrive for Workers-to-database connections with pooling and caching. Use for PostgreSQL/MySQL, Drizzle/Prisma, or encountering pool errors, TLS issues, connection refused."
license: MIT
metadata:
version: "2.0.0"
last_verified: "2025-11-18"
production_tested: true
token_savings: "~58%"
errors_prevented: 6
templates_included: 0
references_included: 1
keywords:
- hyperdrive
- cloudflare hyperdrive
- workers hyperdrive
- postgres workers
- mysql workers
- connection pooling
- query caching
- node-postgres
- pg
- postgres.js
- mysql2
- drizzle hyperdrive
- prisma hyperdrive
- workers rds
- workers aurora
- workers neon
- workers supabase
- database acceleration
- hybrid architecture
- cloudflare tunnel database
- wrangler hyperdrive
- hyperdrive bindings
- local development hyperdrive
---
# Cloudflare Hyperdrive
**Status**: Production Ready ✅ | **Last Verified**: 2025-11-18
---
## What Is Hyperdrive?
Connect Workers to existing PostgreSQL/MySQL databases:
- Global connection pooling
- Query caching
- Reduced latency
- Works with node-postgres, postgres.js, mysql2
---
## Quick Start (5 Minutes)
### 1. Create Hyperdrive Config
```bash
bunx wrangler hyperdrive create my-db \
--connection-string="postgres://user:pass@host:5432/database"
```
Save the `id`!
### 2. Configure Binding
```jsonc
{
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2024-09-23",
"compatibility_flags": ["nodejs_compat"], // REQUIRED!
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "<ID_FROM_STEP_1>"
}
]
}
```
### 3. Install Driver
```bash
bun add pg # or postgres, or mysql2
```
### 4. Query Database
```typescript
import { Client } from 'pg';
export default {
async fetch(request, env, ctx) {
const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
const result = await client.query('SELECT * FROM users LIMIT 10');
await client.end();
return Response.json(result.rows);
}
};
```
**Load `references/setup-guide.md` for complete walkthrough.**
---
## Critical Rules
### Always Do ✅
1. **Enable nodejs_compat** flag (required!)
2. **Use env.HYPERDRIVE.connectionString** (not original DB string)
3. **Close connections** after queries
4. **Handle errors** explicitly
5. **Use connection pooling** (built-in)
6. **Test locally** with wrangler dev
7. **Monitor query performance**
8. **Use prepared statements**
9. **Enable query caching** (automatic)
10. **Secure connection strings** (use secrets)
### Never Do ❌
1. **Never skip nodejs_compat** (drivers won't work)
2. **Never use original DB connection string** in Workers
3. **Never leave connections open** (pool exhaustion)
4. **Never skip error handling** (DB can fail)
5. **Never hardcode credentials** in code
6. **Never exceed connection limits**
7. **Never use eval/Function** (blocked in Workers)
8. **Never skip TLS** for production DBs
9. **Never use blocking queries** (Worker timeout)
10. **Never expose DB errors** to users
---
## Database Drivers
### PostgreSQL (node-postgres)
```typescript
import { Client } from 'pg';
const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
const result = await client.query('SELECT * FROM users');
await client.end();
```
### PostgreSQL (postgres.js)
```typescript
import postgres from 'postgres';
const sql = postgres(env.HYPERDRIVE.connectionString);
const users = await sql`SELECT * FROM users`;
```
### MySQL
```typescript
import mysql from 'mysql2/promise';
const connection = await mysql.createConnection(env.HYPERDRIVE.connectionString);
const [rows] = await connection.execute('SELECT * FROM users');
await connection.end();
```
---
## With Drizzle ORM
```typescript
import { drizzle } from 'drizzle-orm/node-postgres';
import { Client } from 'pg';
const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
const db = drizzle(client);
const users = await db.select().from(usersTable);
await client.end();
```
---
## Common Use Cases
### Use Case 1: Read-Only Queries
```typescript
export default {
async fetch(request, env, ctx) {
const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
const users = await client.query('SELECT * FROM users WHERE active = true');
await client.end();
return Response.json(users.rows);
}
};
```
### Use Case 2: Parameterized Queries
```typescript
const userId = new URL(request.url).searchParams.get('id');
const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
const result = await client.query(
'SELECT * FROM users WHERE id = $1',
[userId]
);
await client.end();
```
### Use Case 3: Transactions
```typescript
const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
try {
await client.query('BEGIN');
await client.query('UPDATE accounts SET balance = balance - 100 WHERE id = $1', [1]);
await client.query('UPDATE accounts SET balance = balance + 100 WHERE id = $1', [2]);
await client.query('COMMIT');
} catch (e) {
await client.query('ROLLBACK');
throw e;
} finally {
await client.end();
}
```
---
## Supported Databases
**PostgreSQL:**
- Amazon RDS
- Amazon Aurora
- Neon
- Supabase
- Railway
- Render
- DigitalOcean
- Any PostgreSQL 11+
**MySQL:**
- Amazon RDS
- Amazon Aurora
- PlanetScale
- Any MySQL 5.7+
---
## Official Documentation
- **Hyperdrive Overview**: https://developers.cloudflare.com/hyperdrive/
- **Get Started**: https://developers.cloudflare.com/hyperdrive/get-started/
- **Configuration**: https://developers.cloudflare.com/hyperdrive/configuration/
---
## Bundled Resources
**References** (`references/`):
- `setup-guide.md` - Complete setup walkthrough (create config, bind, query)
- `connection-pooling.md` - Connection pool configuration and best practices
- `query-caching.md` - Query caching strategies and optimization
- `drizzle-integration.md` - Drizzle ORM integration patterns
- `prisma-integration.md` - Prisma ORM integration patterns
- `supported-databases.md` - Complete list of supported PostgreSQL and MySQL providers
- `tls-ssl-setup.md` - TLS/SSL configuration for secure connections
- `troubleshooting.md` - Common issues and solutions
- `wrangler-commands.md` - Complete wrangler CLI commands for Hyperdrive
**Templates** (`templates/`):
- `postgres-basic.ts` - Basic PostgreSQL with node-postgres
- `postgres-js.ts` - PostgreSQL with postgres.js driver
- `postgres-pool.ts` - PostgreSQL with connection pooling
- `mysql2-basic.ts` - MySQL with mysql2 driver
- `drizzle-postgres.ts` - Drizzle ORM with PostgreSQL
- `drizzle-mysql.ts` - Drizzle ORM with MySQL
- `prisma-postgres.ts` - Prisma ORM with PostgreSQL
- `local-dev-setup.sh` - Local development setup script
- `wrangler-hyperdrive-config.jsonc` - Wrangler configuration example
---
**Questions? Issues?**
1. Check `references/setup-guide.md` for complete setup
2. Verify nodejs_compat flag enabled
3. Ensure using env.HYPERDRIVE.connectionString
4. Check connection properly closed
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |