外部数据库集成总览：D1、Hyperdrive 还是官方 driver
在 Workers 上接外部数据库之前，先判断 D1 是否够用，再在 Hyperdrive 池化 TCP 与数据库官方 HTTP driver 之间选路。
编辑与核验：橙宝书编辑团队 ·
先给结论
结构化数据且查询模式简单时，先评估 D1；必须用 Postgres/MySQL 全集或已有数据库时，外部库有两条路——Hyperdrive 池化 TCP，或数据库官方 HTTP driver。Hyperdrive 不支持 SQLite/libSQL，因此 Turso 只能走官方 driver。
四条连接路径
| 路径 | 适合 | 关键限制 | 上线前必须验证 |
|---|---|---|---|
| D1（先用平台自带） | 结构化数据、单区域读写、查询模式简单 | SQLite 语义；跨库 JOIN 与存储过程不适用 | 读写比例、迁移工具链、容量上限 |
| Hyperdrive + Postgres 生态 | 已有 Postgres（含 Neon、Supabase、CockroachDB、Timescale），需要连接池与缓存 | 强制 TLS；不支持 LISTEN/NOTIFY、advisory locks、SQL 级 prepared statements | 连接串、角色权限、查询延迟 |
| Hyperdrive + MySQL 生态 | 已有 MySQL 5.7–8.x 或 MariaDB（含 PlanetScale） | 同上的 TLS 强制；按官方支持列表核对驱动 | 协议兼容性、慢查询 |
| 数据库官方 HTTP driver | Workers 直接发 HTTP/WebSocket 请求（Supabase PostgREST、Neon serverless、Turso libSQL、TiDB serverless） | 无连接池收益；每次请求自付握手与 TLS 开销 | 冷启动延迟、厂商限流 |
D1 什么时候够用
D1 与 Workers 同区域运行，读路径几乎无网络开销，迁移工具链在平台内闭环。如果数据模型是单租户或少量关联表、没有存储过程和触发器依赖、团队不想运维第二套数据库，先用 D1。判断细节见按数据形态选择存储服务。
需要完整 SQL 能力（窗口函数、CTE、复杂事务隔离）或数据已经在 Supabase/Neon 等外部库里时，不要硬迁回 D1——D1 与 Supabase/Neon 的详细取舍见 D1 vs Supabase/Neon 对比页，本页不重复。
Hyperdrive 的能力与边界
Hyperdrive 在 Cloudflare 边缘维护到源数据库的连接池，并提供查询缓存，把每次冷启动的 TCP/TLS 握手成本摊掉。官方支持范围：
- Postgres 9.0–17.x，以及协议兼容的 Neon、Supabase、CockroachDB、Timescale。
- MySQL 5.7–8.x 与 MariaDB，以及协议兼容的 PlanetScale。
- 强制 TLS，源库必须接受加密连接。
- Postgres 侧不支持 LISTEN/NOTIFY、advisory locks、SQL 级 prepared statements（driver 层的参数化查询不受影响）。
- 不支持 SQLite/libSQL——Turso 与本地 SQLite 文件都不能走 Hyperdrive。
{
"name": "orders-api",
"compatibility_date": "2026-08-25",
"compatibility_flags": ["nodejs_compat"],
"hyperdrive": [
{ "binding": "HYPERDRIVE", "id": "<hyperdrive-config-id>", "localConnectionString": "postgres://user:pass@localhost:5432/postgres" }
]
}按三个问题选路
- 需要 SQL 全集吗？ 不需要、数据模型简单：D1。需要：进下一问。
- 已有外部数据库吗？ 有 Postgres/MySQL：Hyperdrive 优先，连接池对高频短查询收益最大。从零开始：再比 Neon/Supabase/TiDB 的免费额度与冷启动行为。
- 冷启动敏感吗？ 极敏感且用 Postgres：Hyperdrive；可以容忍首次数百毫秒：官方 HTTP driver 更简单，没有额外的 Hyperdrive 配置要维护。
先补数据库知识，再配置连接
Hyperdrive 解决连接池与边缘到数据库的路径，不会替你设计 schema、索引、事务、备份或升级。选择 Postgres 时继续阅读 PostgreSQL 云服务与责任边界；选择 MariaDB 时继续阅读 云上 MariaDB 选型。然后回到本页配置连接，并用相关技术文档网络检查上下游职责是否闭环。
验证与排障
| 现象 | 先检查 | 恢复动作 |
|---|---|---|
Worker 报 connection refused | 源库是否放行 Cloudflare 边缘来源、TLS 是否开启 | 开启 TLS 并放行来源后重试 |
| Hyperdrive 查询超时报错 | 是否使用了 LISTEN/NOTIFY 或 advisory locks | 改写为轮询或队列方案 |
driver 在 Workers 构建失败 | 是否用了 Node 原生 socket 版本 | 换成官方标注支持 Workers 的包与导入路径 |
| 冷启动后首查数百毫秒 | 是否走了 HTTP driver 且源端有 scale-to-zero | 改 Hyperdrive，或接受首查延迟并加缓存 |
远程边界与回滚
创建 Hyperdrive 配置、写入数据库密码类 Secret、部署 Worker 都会修改 Cloudflare 侧状态，本页不自动执行。回滚时按反向顺序操作：先在 wrangler.jsonc 里移除 hyperdrive 绑定并重新部署，再在 Cloudflare Dashboard 删除 Hyperdrive 配置，最后轮换已写入的数据库密码——绑定删除不会吊销 Secret，密码轮换要单独做。
下一步：按数据库选具体教程——Supabase、Neon、Turso、TiDB；绑定与密钥的通用规则见 Bindings、环境与 Secrets。
官方来源
这篇内容帮你完成目标了吗？
内测反馈只在当前浏览器生成，不会自动上传。