# Cloudflare Hyperdrive **状态**：生产就绪 ✅ **最后更新**：2025-11-23 **依赖项**：cloudflare-worker-base（建议用于 Worker 设置） **最新版本**：wrangler@4.50.0、pg@8.16.3+（最小）、postgres@3.4.7、mysql2@3.15.3 **最近更新（2025）**： * **2025 年 7 月**：可配置的连接数（最少 5 个，最多 ~20 个免费/~100 个付费） * **2025 年 5 月**：缓存命中速度提高 5 倍（区域预准备语句缓存），FedRAMP 中等授权 * **2025 年 4 月**：免费计划可用性（10 个配置），MySQL GA 支持 * **2025 年 3 月**：延迟减少 90%（数据库附近的池）、IP 访问控制（标准 CF IP 范围） * **nodejs_compat_v2** ：pg 驱动程序不再需要 node_compat 模式（通过兼容性日期 2024-09-23+ 自动启用） * **限制**：每个帐户 25 个 Hyperdrive 配置（付费），每个帐户 10 个（免费） ** ** ## 快速入门（5 分钟） ### 1\.创建超空间驱动器配置 # 对于 PostgreSQL npx wrangler hyperdrive 创建 my-postgres-db \ --connection-string="postgres://用户:密码@db-host.cloud:5432/database" # 对于 MySQL npx wrangler hyperdrive 创建 my-mysql-db \ --connection-string="mysql://用户:密码@db-host.cloud:3306/database" # 输出： # ✅ 成功创建 Hyperdrive 配置 # # [[超级光驱]] # 绑定 = "HYPERDRIVE" #id =“a76a99bc-7901-48c9-9c15-c4b11b559606” **保存`id`值** \-您在下一步中将需要它！ ** ** ### 2\.在 wrangler.jsonc 中配置绑定添加到您的“wrangler.jsonc”： { “姓名”：“我的工人”， "main": "src/index.ts", “兼容性日期”：“2024-09-23”， "compatibility_flags": ["nodejs_compat"], // 数据库驱动程序必需 “超级光驱”：[ { "binding": "HYPERDRIVE", // 可用作 env.HYPERDRIVE "id": "a76a99bc-7901-48c9-9c15-c4b11b559606" // 从牧马人超驱动器创建 } ] } **关键：** * 对于所有数据库驱动程序来说，`nodejs_compat` 标志是**必需的** * `binding` 是您在代码中访问 Hyperdrive 的方式 (`env.HYPERDRIVE`) * `id` 是 Hyperdrive 配置 ID（不是您的数据库 ID） ** ** ### 3\.安装数据库驱动 # 对于 PostgreSQL（选择一项） npm install pg # node-postgres （最常见） npm install postgres # postgres.js （现代，最低 v3.4.5） # 对于 MySQL npm install mysql2 # mysql2 (最低 v3.13.0) ** ** ### 4\.查询您的数据库 **带有节点 postgres (pg) 的 PostgreSQL：** 从“pg”导入{客户端}；类型绑定 = { 超光速：超光速； }; 导出默认值{ 异步获取（请求：请求，env：绑定，ctx：ExecutionContext）{ 常量客户端 = 新客户端({ 连接字符串：env.HYPERDRIVE.connectionString }); 等待客户端.connect(); 尝试{ const result = wait client.query('SELECT * FROM users LIMIT 10'); 返回 Response.json({ 用户: result.rows }); }最后{ // 发送响应后清理连接 ctx.waitUntil(client.end()); } } }; **MySQL 与 mysql2:** 从“mysql2/promise”导入{createConnection}；导出默认值{ 异步获取（请求：请求，env：绑定，ctx：ExecutionContext）{ const 连接 = 等待 createConnection({ 主机：env.HYPERDRIVE.host，用户：env.HYPERDRIVE.user，密码：env.HYPERDRIVE.密码，数据库：env.HYPERDRIVE.database，端口：env.HYPERDRIVE.port， disableEval: true // Workers 必需（不支持 eval()） }); 尝试{ const [rows] =等待connection.query('SELECT * FROM users LIMIT 10'); 返回 Response.json({ 用户: 行 }); }最后{ ctx.waitUntil(connection.end()); } } }; ** ** ### 5\.部署 npx 牧马人部署 **就是这样！** 您的 Worker 现在通过 Hyperdrive 连接到您现有的数据库： * ✅ 全局连接池 * ✅ 自动查询缓存 * ✅ 减少延迟（消除 7 次往返） ** ** ## 超空间驱动器的工作原理 Hyperdrive 通过以下方式消除了 7 次连接往返（TCP + TLS + auth）： * Worker 附近的边缘连接设置（低延迟） * 数据库附近的连接池（2025 年 3 月：延迟减少 90%） * 边缘查询缓存（2025 年 5 月：缓存命中速度提高 5 倍） **结果**：单区域数据库感觉是全球分布的。 ** ** ## 设置步骤 ### 先决条件 * 具有 Workers 访问权限的 Cloudflare 帐户 * PostgreSQL (v9.0-17.x) 或 MySQL (v5.7-8.x) 数据库 * 通过公共互联网（需要 TLS/SSL）或专用网络（Cloudflare Tunnel）访问数据库 * **2025 年 4 月**：适用于免费计划（10 个配置）和付费计划（25 个配置） ### 连接字符串格式 # PostgreSQL postgres://用户:密码@主机:5432/数据库 postgres://用户:密码@主机:5432/database?sslmode=require #MySQL mysql://用户名:密码@主机:3306/数据库 # 对特殊字符进行 URL 编码：p@ssw$rd → p%40ssw%24rd ** ** ## 连接模式 ### 单连接（pg.Client） const client = new Client({ connectionString: env.HYPERDRIVE.connectionString }); 等待客户端.connect(); const result = wait client.query('SELECT ...'); ctx.waitUntil(client.end()); // 关键：非阻塞清理 **用于** ：简单查询，每个请求单个查询 ### 连接池（pg.Pool）常量池=新池（{ 连接字符串：env.HYPERDRIVE.connectionString，最大：5 // 关键：工作人员限制为 6 个连接（2025 年 7 月：可配置 ~20 个免费，~100 个付费） }); const [结果1，结果2] =等待Promise.all([ pool.query('选择...'), pool.query('选择...') ]); ctx.waitUntil(pool.end()); **用于** ：单个请求中的并行查询 ### 连接清理规则 **始终使用`ctx.waitUntil(client.end())`** \- 发送响应后进行非阻塞清理 **切勿使用`await client.end()`** \- 阻塞响应，增加延迟 ** ** ## ORM 集成 ### 毛毛雨 ORM import { drizzle } from "drizzle-orm/postgres-js"; 从“postgres”导入 postgres； const sql = postgres(env.HYPERDRIVE.connectionString, { max: 5 }); const db = 细雨(sql); const allUsers =等待db.select().from(users); ctx.waitUntil(sql.end()); ### Prisma ORM 从“@prisma/adapter-pg”导入 { PrismaPg }；从“@prisma/client”导入 { PrismaClient }；从“pg”导入{池}； const pool = new Pool({ connectionString: env.HYPERDRIVE.connectionString, max: 5 }); const 适配器 = new PrismaPg(pool); const prisma = new PrismaClient({ 适配器 }); const 用户 = 等待 prisma.user.findMany(); ctx.waitUntil(pool.end()); **注意**：Prisma 需要驱动适配器（`@prisma/adapter-pg`）。 ** ** ## 本地发展 **选项 1：环境变量（推荐）** 导出 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://用户:密码@localhost:5432/local_db" npx牧马人开发可以安全提交配置，wrangler.jsonc 中没有凭据。 **选项 2：wrangler.jsonc 中的 localConnectionString** {“hyperdrive”：[{“绑定”：“HYPERDRIVE”，“id”：“prod-id”，“localConnectionString”：“postgres：//...”}]} ⚠️ 不要将凭据提交给版本控制。 **选项 3：远程开发** npx wrangler dev --remote # ⚠️ 使用 PRODUCTION 数据库 ** ** ## 查询缓存 **缓存**：SELECT（非变异查询）**不缓存**：INSERT、UPDATE、DELETE、易失性函数（LASTVAL、LAST_INSERT_ID） **2025 年 5 月**：通过区域预准备语句缓存，缓存命中速度提高 5 倍。 **对于 postgres.js 至关重要：** const sql = postgres(env.HYPERDRIVE.connectionString, { 准备：true // 缓存所需 }); **检查缓存状态：** response.headers.get('cf-cache-status'); // 命中、未命中、绕过、过期 ** ** ## TLS/SSL 配置 **SSL 模式** ：“require”（默认）、“verify-ca”（验证 CA）、“verify-full”（验证 CA + 主机名） **服务器证书（verify-ca/verify-full）：** npx 牧马人证书上传证书颁发机构 --ca-cert root-ca.pem --name my-ca-cert npx Wrangler hyperdrive create my-db --connection-string="postgres://..." --ca-certificate-id --sslmode verify-full **客户端证书 (mTLS)：** npx 牧马人证书上传 mtls-certificate --cert client-cert.pem --key client-key.pem --name my-cert npx Wrangler hyperdrive create my-db --connection-string="postgres://..." --mtls-certificate-id ** ** ## 私有数据库访问（Cloudflare Tunnel）连接到专用网络（VPC、本地）中的数据库： # 1.安装cloudflare（macOS：brew install cloudflare/cloudflare/cloudflared） # 2.创建隧道 cloudflared 隧道创建 my-db-tunnel # 3.配置config.yml # 隧道： # 入口： # - 主机名：db.example.com # 服务：tcp://localhost:5432 # 4.运行隧道 cloudflared 隧道运行 my-db-tunnel # 5. 创建超空间 npx 牧马人 hyperdrive 创建 my-private-db --connection-string="postgres://user:password@db.example.com:5432/database" ** ** ## 关键规则 ### 总是这样做 ✅ 在“compatibility_flags”中包含“nodejs_compat” ✅ 使用“ctx.waitUntil(client.end())”进行连接清理 ✅ 为连接池设置“max: 5”（工作线程限制：6） ✅ 在数据库上启用 TLS/SSL（Hyperdrive 需要它） ✅ 使用准备好的语句进行缓存（postgres.js：“prepare: true”） ✅ 设置“disableEval: true” mysql2 驱动程序 ✅ 使用 try/catch 优雅地处理错误 ✅ 使用本地开发连接字符串的环境变量 ✅ 在部署之前使用 `wrangler dev` 进行本地测试 ### 永远不要这样做 ❌ 跳过 `nodejs_compat` 标志（导致“No such module”错误） ❌ 直接使用私有 IP 地址（改为使用 Cloudflare Tunnel） ❌ 使用 `await client.end()`（阻止响应，使用 `ctx.waitUntil()`） ❌ 设置连接池最大值 > 5（超过 Workers 6 个连接限制） ❌ 将所有查询包装在事务中（限制连接复用） ❌ 使用 SQL 级 PREPARE/EXECUTE/DEALLOCATE（不支持） ❌ 使用咨询锁、LISTEN/NOTIFY（PostgreSQL 不支持的功能） ❌ 在 MySQL 中使用多语句查询（不支持） ❌ 将数据库凭据提交到版本控制 ** ** ## Wrangler 命令参考 # 创建 Hyperdrive 配置牧马人 hyperdrive create <名称> --connection-string="postgres://..." # 列出所有 Hyperdrive 配置牧马人超光速驱动器列表 # 获取配置的详细信息牧马人 hyperdrive 获取 # 更新连接字符串牧马人超驱动器更新 --connection-string="postgres://..." # 删除配置牧马人 hyperdrive 删除 # 上传CA证书牧马人证书上传证书颁发机构 --ca-cert <文件>.pem --name <名称> # 上传客户端证书对牧马人证书上传 mtls-certificate --cert .pem --key .pem --name <名称> ** ** ## 支持的数据库 **PostgreSQL (v9.0-17.x)**：AWS RDS/Aurora、Google Cloud SQL、Azure、Neon、Supabase、PlanetScale、Timescale、CockroachDB、Materialize、Fly.io、pgEdge、Prisma Postgres **MySQL (v5.7-8.x)**：AWS RDS/Aurora、Google Cloud SQL、Azure、PlanetScale、MariaDB（2025 年 4 月正式版） **不支持**：SQL Server、MongoDB、Oracle ** ** ## 不支持的功能 ### PostgreSQL * SQL 级准备语句（`PREPARE`、`EXECUTE`、`DEALLOCATE`） * 咨询锁 *“听”和“通知” * 每个会话状态修改 ### MySQL * 查询中的非 UTF8 字符 *`USE`语句 * 多语句查询 * 协议级准备好的语句（`COM_STMT_PREPARE`） *`COM_INIT_DB`消息 * 除 `caching_sha2_password` 或 `mysql_native_password` 之外的身份验证插件 **解决方法**：对于不受支持的功能，创建第二个直接客户端连接（不使用 Hyperdrive）。 ** ** ## 性能最佳实践 1. **避免长时间运行的事务** \- 限制连接复用 2. **使用准备好的语句** \- 启用查询缓存（postgres.js: `prepare: true`） 3. **设置最大：5 个池** \- 保持在 Workers 的 6 个连接限制内 4. **如果不需要，禁用 fetch_types** \- 减少延迟 (postgres.js) 5. **使用 ctx.waitUntil() 进行清理** \- 非阻塞连接关闭 6. **缓存友好的查询** \- 优先选择 SELECT 而不是复杂的联接 7. **对经常查询的列建立索引** \- 提高查询性能 8. **使用 Hyperdrive 分析进行监控** \- 跟踪缓存命中率和延迟 ** ** ## 故障排除请参阅“references/troubleshooting.md”以获取完整的错误参考和解决方案。 **快速修复：** 错误 |解决方案 ---|--- “没有这样的模块'节点：*'”|将“nodejs_compat”添加到compatibility_flags “数据库不支持 TLS”|在您的数据库上启用 SSL/TLS “连接被拒绝”|检查防火墙规则，允许公共互联网或使用隧道 “无法获取连接” |使用 ctx.waitUntil() 进行清理，避免长时间事务 “不允许从字符串生成代码”|在 mysql2 配置中设置 `disableEval: true` “错误的主机名” |验证 DNS 解析，检查是否有拼写错误 “无效的数据库凭据”|检查用户名/密码（区分大小写） ** ** ## 指标和分析 [Hyperdrive 仪表板]() → 选择配置 → 指标选项卡 **可用**：查询计数、缓存命中率、查询延迟（p50/p95/p99）、连接延迟、查询/结果字节、错误率 ** ** ## 凭证轮换 # 选项 1：创建新配置（零停机）牧马人 hyperdrive 创建 my-db-v2 --connection-string="postgres://new-creds..." # 更新 wrangler.jsonc，部署，删除旧配置 # 选项 2：更新现有的牧马人超光速驱动更新 --connection-string="postgres://new-creds..." **最佳实践**：单独的暂存/生产配置。 * * * ＃＃参考 * [官方文档]() * [入门指南]() * [Hyperdrive 的工作原理]() * [查询缓存]() * [本地开发]() * [TLS/SSL 证书]() * [问题排查指南]() * [牧马人命令]() * [支持的数据库]() ** ** **最后更新**：2025 年 11 月 23 日 **软件包版本**：wrangler@4.50.0、pg@8.16.3+（最低）、postgres@3.4.7、mysql2@3.15.3 **生产测试**：基于官方 Cloudflare 文档和社区示例

Cloudflare Hyperdrive

包含技能