Workers 连接 TiDB：@tidbcloud/serverless 走 HTTP
Workers 不能直连 TCP，用 @tidbcloud/serverless 通过 HTTP 访问 TiDB Cloud Starter/Essential。
编辑与核验：橙宝书编辑团队 ·
先给结论
TiDB 是 MySQL 协议兼容的分布式数据库，但 Workers 不能直连 TCP。官方路径是 @tidbcloud/serverless：它把查询封装成 HTTP 请求。Hyperdrive 官方支持列表未列 TiDB，兼容性未经验证，不作为推荐路径。
适用范围与限制
- 仅支持 TiDB Cloud Starter / Essential 集群；自建 TiDB 或 Dedicated 集群不在该 driver 的支持范围内。
- 所有查询走 HTTPS，无连接池收益；高频短查询场景要实测延迟是否可接受。
- Hyperdrive 支持 MySQL 5.7–8.x 及协议兼容库，但官方列表未点名 TiDB。即便协议层面兼容，也不要把未验证的组合用于生产。
准备集群与凭据
在 TiDB Cloud 控制台创建 Starter 集群后，从连接面板拿到标准 MySQL 连接串，形如 mysql://user:pass@host/db，整体存为一个 Secret：
npx wrangler secret put DATABASE_URL连接串里含密码，必须走 wrangler secret，不要写进 vars 或提交仓库。泄露时在 TiDB Cloud 控制台重置密码并更新 Secret。
Worker 代码
npm install @tidbcloud/serverlessimport { connect } from '@tidbcloud/serverless';
interface Env {
DATABASE_URL: string;
}
export default {
async fetch(request, env: Env): Promise<Response> {
const conn = connect({ url: env.DATABASE_URL });
try {
const rows = await conn.execute('SELECT id, title FROM notes LIMIT 10');
return Response.json({ notes: rows });
} catch (error) {
return Response.json({ error: String(error) }, { status: 502 });
}
},
};connect 每次调用创建的是无状态 HTTP 客户端，不需要在请求间复用，也没有连接要关闭。该路径不需要任何 wrangler 绑定。
验证与排障
curl -s https://<worker>.workers.dev/notes| 现象 | 先检查 | 恢复动作 |
|---|---|---|
401/认证失败 | DATABASE_URL 中的用户名密码是否与控制台一致 | 在控制台重置密码后 wrangler secret put 更新 |
| 连接超时 | 集群类型是否为 Starter/Essential | Dedicated 集群需改用其它接入方式（不在本页范围） |
| TLS 相关报错 | 连接串是否来自控制台连接面板（默认带 TLS 参数） | 重新复制完整连接串，不手工删参数 |
| 高频查询延迟高 | 是否该场景本就需要连接池 | 评估换 Postgres 生态 + Hyperdrive，见集成总览 |
远程边界与回滚
创建 TiDB Cloud 集群、写入 DATABASE_URL Secret、部署 Worker 都会修改远程状态，本教程不自动执行。回滚时：代码侧删除相关路由并重新部署，Workers 不持有连接，无需排空；随后在 Cloudflare 侧删除 DATABASE_URL Secret，并在 TiDB Cloud 控制台重置数据库密码。若要整体回退到 D1，先把数据导出再导入 D1——注意 TiDB 是 MySQL 方言、D1 是 SQLite 方言，schema 需要逐表改写并验证，不是纯数据搬运。
下一步：选型回顾见外部数据库集成总览；上线后的监控接入见可观测性。
官方来源
这篇内容帮你完成目标了吗？
内测反馈只在当前浏览器生成，不会自动上传。