Hyperdrive 说明文档

# Hyperdrive 通过连接池、边缘设置和查询缓存加速 Workers 的数据库查询。 ## 核心功能 - **连接池**：持久连接消除了 TCP/TLS/认证握手（约 7 次往返） - **边缘设置**：在边缘进行连接协商，在源站附近进行连接池管理 - **查询缓存**：自动缓存非修改类查询（默认 60 秒 TTL） - **支持**：PostgreSQL、MySQL 及兼容数据库（CockroachDB, Timescale, PlanetScale, Neon, Supabase） ## 架构 Worker → Edge (设置) → Pool (数据库附近) → Origin ↓ 缓存读取 Cache ## 快速开始 bash # 创建配置 npx wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host:5432/db" # wrangler.jsonc { "compatibility_flags": ["nodejs_compat"], "hyperdrive": [{"binding": "HYPERDRIVE", "id": ""}] } typescript import { Client } from "pg"; export default { async fetch(req: Request, env: Env): Promise { const client = new Client({ connectionString: env.HYPERDRIVE.connectionString, }); await client.connect(); const result = await client.query("SELECT * FROM users WHERE id = $1", [123]); await client.end(); return Response.json(result.rows); }, }; ## 适用场景 ✅ 全球访问单区域数据库、高读取比例、热门查询、连接密集型负载 ❌ 写入密集型、实时数据（<1s）、靠近数据库的单区域应用 **? 搭配智能放置 (Smart Placement)**：对于执行多次查询的 Workers，在数据库附近执行以最小化延迟。 ## 驱动选择 | 驱动 | 适用场景 | 备注 | |--------|----------|-------| | **pg** (推荐) | 通用、TypeScript、生态兼容 | 稳定、广泛使用、兼容大多数 ORM | | **postgres.js** | 高级功能、模板字符串、流式处理 | 比 pg 更轻量，默认开启 `prepare: true` | | **mysql2** | MySQL/MariaDB/PlanetScale | 仅限 MySQL，支持成熟度较低 | ## 阅读顺序 | 初次接触 Hyperdrive | 实施中 | 故障排除 | |-------------------|--------------|-----------------| | 1. README (本文) | 1. [configuration.md](./configuration.md) | 1. [gotchas.md](./gotchas.md) | | 2. [configuration.md](./configuration.md) | 2. [api.md](./api.md) | 2. [patterns.md](./patterns.md) | | 3. [api.md](./api.md) | 3. [patterns.md](./patterns.md) | 3. [api.md](./api.md) | ## 本参考文档内容 - [configuration.md](./configuration.md) - 设置、wrangler 配置、智能放置 - [api.md](./api.md) - 绑定 API、查询模式