cloudflare-hyperdrive

用途

Cloudflare Hyperdrive 用于将 Cloudflare Workers 连接到已有的 PostgreSQL 或 MySQL 数据库。它通过在全球边缘节点建立连接、在数据库附近进行连接池化以及查询缓存，消除 TCP、TLS 和认证等多次往返，从而降低延迟，使单区域数据库获得接近全球分布式的访问体验。

主要能力

全球连接池化：在数据库附近维护连接池，减少每次请求建立连接的开销。
自动查询缓存：在边缘缓存查询结果，提升缓存命中速度。
支持 PostgreSQL 和 MySQL：PostgreSQL 版本范围 v9.0-17.x，MySQL 版本范围 v5.7-8.x。
可配置连接数：2025 年 7 月起支持配置连接数量，免费计划约 20，付费计划约 100。
免费计划可用：2025 年 4 月起免费计划提供 10 个配置，付费计划提供 25 个配置。
IP 访问控制：2025 年 3 月起支持标准 Cloudflare IP 范围。

使用方式

创建 Hyperdrive 配置：

npx wrangler hyperdrive create my-postgres-db \
  --connection-string="postgres://user:password@db-host.cloud:5432/database"

MySQL 使用 mysql:// 连接字符串。命令会输出配置 id，需要保存。

在 wrangler.jsonc 中配置绑定：

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23",
  "compatibility_flags": ["nodejs_compat"],
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "a76a99bc-7901-48c9-9c15-c4b11b559606"
    }
  ]
}

注意：nodejs_compat 标志对所有数据库驱动都是必需的；binding 是代码中访问 Hyperdrive 的名称（env.HYPERDRIVE）；id 是 Hyperdrive 配置 ID，不是数据库 ID。

安装数据库驱动：

npm install pg           # node-postgres
npm install postgres     # postgres.js（最低 v3.4.5）
npm install mysql2       # mysql2（最低 v3.13.0）

查询数据库。PostgreSQL 使用 pg 的示例：

import { Client } from "pg";

type Bindings = {
  HYPERDRIVE: Hyperdrive;
};

export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const client = new Client({
      connectionString: env.HYPERDRIVE.connectionString
    });

    await client.connect();

    try {
      const result = await client.query('SELECT * FROM users LIMIT 10');
      return Response.json({ users: result.rows });
    } finally {
      ctx.waitUntil(client.end());
    }
  }
};

MySQL 使用 mysql2 的示例：

import { createConnection } from "mysql2/promise";

export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const connection = await createConnection({
      host: env.HYPERDRIVE.host,
      user: env.HYPERDRIVE.user,
      password: env.HYPERDRIVE.password,
      database: env.HYPERDRIVE.database,
      port: env.HYPERDRIVE.port,
      disableEval: true
    });

    try {
      const [rows] = await connection.query('SELECT * FROM users LIMIT 10');
      return Response.json({ users: rows });
    } finally {
      ctx.waitUntil(connection.end());
    }
  }
};

部署：

npx wrangler deploy

连接模式与清理规则

单连接（pg.Client）：适用于简单查询、每请求单次查询。
连接池（pg.Pool）：适用于单请求内并行查询，max 建议设为 5（Workers 限制为 6 个连接）。
清理规则：始终使用 ctx.waitUntil(client.end()) 进行非阻塞清理，不要使用 await client.end()，后者会阻塞响应并增加延迟。

ORM 集成

Drizzle ORM：

import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";

const sql = postgres(env.HYPERDRIVE.connectionString, { max: 5 });
const db = drizzle(sql);
const allUsers = await db.select().from(users);
ctx.waitUntil(sql.end());

Prisma ORM：不要在 Workers 中跨请求复用 Prisma 客户端，必须每个请求创建新客户端。Prisma 需要驱动适配器（@prisma/adapter-pg）。

本地开发

本地 Hyperdrive 连接不支持 SSL，这会影响要求 SSL 的数据库（如 Neon、多数云提供商）。可使用条件连接：

const url = env.isLocal ? env.DB_URL : env.HYPERDRIVE.connectionString;
const client = postgres(url, {
  fetch_types: false,
  max: 2,
});

或使用 wrangler dev --remote（注意：会连接生产数据库）。SSL 支持计划于 2026 年提供。

本地连接也可通过环境变量设置：

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/db"
npx wrangler dev

已知问题与预防

文档列出 11 个已知问题，包括：Windows/macOS 本地开发主机名解析失败；postgres.js 使用 IP 地址会挂起；MySQL 8.0.43 认证插件不支持；本地 SSL/TLS 不支持远程数据库；事务模式下 SET 语句不跨查询持久；Prisma 客户端复用导致挂起；Neon serverless 驱动与 Hyperdrive 不兼容；Supabase 必须使用直连字符串而非池化连接；Drizzle ORM 配合 Nitro 3 的 useDatabase 失败率高；postgres.js 版本要求（最低 3.4.5）；基于 WebSocket 的数据库驱动不兼容。每个问题均提供了错误信息、原因和预防方案。

适用场景

在 Cloudflare Workers 中访问已有的 PostgreSQL 或 MySQL 数据库。
需要降低数据库连接延迟、减少连接往返次数的应用。
使用 Drizzle 或 Prisma 等 ORM 的 Workers 项目。
单区域数据库需要服务全球用户的场景。

限制

仅支持 PostgreSQL 和 MySQL。
免费计划 10 个配置，付费计划 25 个配置。
本地开发不支持 SSL。
需要 nodejs_compat 兼容标志。
部分驱动和 ORM 存在兼容性限制，需参考已知问题。