cloudflare-hyperdrive

Cloudflare Hyperdrive 用于将 Cloudflare Workers 连接到已有的 PostgreSQL/MySQL 数据库，提供全局连接池、查询缓存和更低的访问延迟，并可与 node-postgres、postgres.js、mysql2 等驱动配合使用。

主要能力

全局连接池：为 Workers 到数据库的连接提供连接池管理。
查询缓存：自动启用查询缓存。
降低延迟：减少访问数据库的延迟。
驱动兼容：支持 node-postgres、postgres.js、mysql2。
ORM 支持：可用于 Drizzle ORM 与 Prisma ORM 的集成模式。
支持的数据库：PostgreSQL 侧包括 Amazon RDS、Amazon Aurora、Neon、Supabase、Railway、Render、DigitalOcean 以及任何 PostgreSQL 11+；MySQL 侧包括 Amazon RDS、Amazon Aurora、PlanetScale 以及任何 MySQL 5.7+。

使用方式

创建 Hyperdrive 配置（示例）： bunx wrangler hyperdrive create my-db
--connection-string="postgres://user:pass@host:5432/database" 保存返回的 id。
配置绑定。在 Worker 配置中加入 hyperdrive 绑定，并必须启用 nodejs_compat 兼容标志： { "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2024-09-23", "compatibility_flags": ["nodejs_compat"], "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "<ID_FROM_STEP_1>" } ] }
安装驱动，例如 bun add pg（或 postgres、mysql2）。
查询数据库（node-postgres 示例）： 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);
```
} };

其他驱动示例

postgres.js： import postgres from 'postgres'; const sql = postgres(env.HYPERDRIVE.connectionString); const users = await sqlSELECT * FROM users;
MySQL（mysql2）： import mysql from 'mysql2/promise'; const connection = await mysql.createConnection(env.HYPERDRIVE.connectionString); const [rows] = await connection.execute('SELECT * FROM users'); await connection.end();
Drizzle ORM： 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();

常见使用场景

只读查询：连接后执行 SELECT 查询并返回 JSON。
参数化查询：使用占位符（如 $1）传递参数，示例中将 URL 查询参数 id 传入查询。
事务：以 BEGIN/COMMIT/ROLLBACK 包裹多条更新语句，并在 finally 中关闭连接。

关键规则（资料明确列出）始终做：启用 nodejs_compat 标志；使用 env.HYPERDRIVE.connectionString 而非原始数据库连接字符串；查询后关闭连接；显式处理错误；使用内置连接池；使用 wrangler dev 本地测试；监控查询性能；使用预处理语句；启用查询缓存（自动）；保护连接字符串（使用 secrets）。绝不要做：不要跳过 nodejs_compat（否则驱动无法工作）；不要在 Workers 中使用原始数据库连接字符串；不要让连接保持打开（会导致连接池耗尽）；不要跳过错误处理；不要在代码中硬编码凭据；不要超出连接限制；不要使用 eval/Function（Workers 中已被阻止）；生产数据库不要跳过 TLS；不要使用阻塞式查询（Worker 会超时）；不要向用户暴露数据库错误。

适用场景适用于 Workers 访问外部 PostgreSQL/MySQL、使用 Drizzle/Prisma 等 ORM、需要连接池管理和查询缓存、以及需要处理连接池错误或 TLS 配置的场景。

限制与缺失信息

资料未说明收费、价格或计费方式。
资料未提供性能提升的具体数值或基准测试结果。
资料未说明平台可用性限制之外的配额细节。
资料未提供 Prisma 集成的完整代码示例（仅列出参考资料名称）。
资料未提供 TLS/SSL 配置的具体步骤（仅列出参考资料名称）。
资料未提供 troubleshooting 的具体条目内容（仅列出参考资料名称）。

官方文档

Hyperdrive Overview: https://developers.cloudflare.com/hyperdrive/
Get Started: https://developers.cloudflare.com/hyperdrive/get-started/
Configuration: https://developers.cloudflare.com/hyperdrive/configuration/

技能介绍