Hyperdrive 支持 MySQL 及 MySQL 兼容数据库、常用驱动以及使用这些驱动的对象关系映射(ORM)库。
要创建连接现有 MySQL 数据库的 Hyperdrive,使用 Wrangler CLI 或 Cloudflare 仪表板 ↗。
使用 Wrangler 时,将 --connection-string 的占位值替换为数据库连接字符串:
# wrangler v3.11 and above required
npx wrangler hyperdrive create my-first-hyperdrive --connection-string="mysql://user:password@database.host.example.com:3306/databasenamehere"上述命令会输出 Hyperdrive ID,需在 Workers 项目的 Wrangler 配置文件 中设置:
在 wrangler.jsonc 中添加 Node.js 兼容性标志和 Hyperdrive 绑定(binding):
{
// required for database drivers to function
"compatibility_flags": [
"nodejs_compat"
],
// Set this to today's date
"compatibility_date": "2026-08-17",
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "<your-hyperdrive-id-here>"
}
]
}compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-08-17"
[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"这使 Hyperdrive 在 Worker 内生成动态连接字符串,可传给现有数据库驱动。请参阅驱动示例了解如何配合 Hyperdrive 设置数据库驱动。
分步指南请参阅示例文档,了解如何与多个热门数据库提供商设置 Hyperdrive。
Hyperdrive 使用 Workers TCP socket 支持 建立到数据库的 TCP 连接。下表列出支持的驱动及 Hyperdrive 所需的最低版本:
| 驱动 | 文档 | 最低版本要求 | 说明 |
|---|---|---|---|
| mysql2(推荐) | mysql2 文档 ↗ | mysql2@3.13.0 |
支持 Workers 和 Pages。建议使用 Promise API。 |
| mysql | mysql 文档 ↗ | mysql@2.18.0 |
需要 compatibility_flags = ["nodejs_compat"] 和 compatibility_date = "2024-09-23" — 请参阅 Node.js 兼容性。需要 wrangler 3.78.7 或更高版本。 |
| Drizzle | Drizzle 文档 ↗ | 需要 mysql2@3.13.0 |
|
| Kysely | Kysely 文档 ↗ | 需要 mysql2@3.13.0 |
^ 标记的库可使用 mysql 或 mysql2 作为依赖。
未列出的其他驱动和 ORM 也可能受支持:此列表并非详尽。
数据库驱动(包括 mysql 和 mysql2)需要 Node.js 兼容性,须为 Workers 项目配置。
要为 Worker 或 Pages 项目启用内置运行时 API 和 polyfill,请在你的 Wrangler 配置文件中添加 nodejs_compat 兼容性标志,并将兼容性日期设置为 2024 年 9 月 23 日或更高版本。这将为 Workers 项目启用 Node.js 兼容性。
{
"compatibility_flags": [
"nodejs_compat"
],
// Set this to today's date
"compatibility_date": "2026-08-17"
}compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-08-17"连接源数据库时,Hyperdrive 支持以下 MySQL TLS/SSL 连接模式:
| 模式 | 是否支持 | 详情 |
|---|---|---|
DISABLED |
否 | Hyperdrive 不支持不安全的明文连接。 |
PREFERRED |
否(使用 REQUIRED) |
Hyperdrive 始终使用 TLS。 |
REQUIRED |
是(默认) | 需要 TLS,并验证服务器证书(基于 WebPKI)。 |
VERIFY_CA |
是 | 验证服务器 TLS 证书由客户端上的根 CA 签名。 |
VERIFY_IDENTITY |
是 | 除 VERIFY_CA 检查外,Hyperdrive 要求数据库主机名与证书上的 Subject Alternative Name (SAN) 或 Common Name (CN) 匹配。 |
有关如何为 Hyperdrive 配置 VERIFY_CA 或 VERIFY_IDENTITY TLS (SSL) 模式的详情,请参阅 SSL/TLS 证书 文档。
以下示例展示如何:
- 使用数据库驱动创建数据库客户端。
- 传入 Hyperdrive 连接字符串并连接数据库。
- 通过 Hyperdrive 查询数据库。
以下 Workers 代码展示如何使用 mysql2 ↗ 配合 Hyperdrive 的 Promise API。
安装 mysql2 ↗ 驱动:
npm i mysql2@>3.13.0yarn add mysql2@>3.13.0pnpm add mysql2@>3.13.0bun add mysql2@>3.13.0在 wrangler.jsonc 中添加所需的 Node.js 兼容性标志和 Hyperdrive 绑定:
在 wrangler.jsonc 中添加 Node.js 兼容性标志和 Hyperdrive 绑定(binding):
{
// required for database drivers to function
"compatibility_flags": [
"nodejs_compat"
],
// Set this to today's date
"compatibility_date": "2026-08-17",
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "<your-hyperdrive-id-here>"
}
]
}compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-08-17"
[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"创建新的 connection 实例并传入 Hyperdrive 参数:
// mysql2 v3.13.0 or later is required
import { createConnection } from "mysql2/promise";
export default {
async fetch(request, env, ctx): Promise<Response> {
// Create a new connection on each request. Hyperdrive maintains the underlying
// database connection pool, so creating a new connection is fast.
const connection = await createConnection({
host: env.HYPERDRIVE.host,
user: env.HYPERDRIVE.user,
password: env.HYPERDRIVE.password,
database: env.HYPERDRIVE.database,
port: env.HYPERDRIVE.port,
// Required to enable mysql2 compatibility for Workers
disableEval: true,
});
try {
// Sample query
const [results, fields] = await connection.query("SHOW tables;");
// Return result rows as JSON
return Response.json({ results, fields });
} catch (e) {
console.error(e);
return Response.json(
{ error: e instanceof Error ? e.message : e },
{ status: 500 },
);
}
},
} satisfies ExportedHandler<Env>;以下 Workers 代码展示如何使用 mysql ↗ 配合 Hyperdrive。
安装 mysql ↗ 驱动:
npm i mysqlyarn add mysqlpnpm add mysqlbun add mysql在 wrangler.jsonc 中添加所需的 Node.js 兼容性标志和 Hyperdrive 绑定:
在 wrangler.jsonc 中添加 Node.js 兼容性标志和 Hyperdrive 绑定(binding):
{
// required for database drivers to function
"compatibility_flags": [
"nodejs_compat"
],
// Set this to today's date
"compatibility_date": "2026-08-17",
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "<your-hyperdrive-id-here>"
}
]
}compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-08-17"
[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"创建新连接并传入 Hyperdrive 参数:
import { createConnection } from "mysql";
export default {
async fetch(request, env, ctx): Promise<Response> {
const result = await new Promise<any>((resolve) => {
// Create a connection using the mysql driver with the Hyperdrive credentials (only accessible from your Worker).
const connection = createConnection({
host: env.HYPERDRIVE.host,
user: env.HYPERDRIVE.user,
password: env.HYPERDRIVE.password,
database: env.HYPERDRIVE.database,
port: env.HYPERDRIVE.port,
});
connection.connect((error: { message: string }) => {
if (error) {
throw new Error(error.message);
}
// Sample query
connection.query("SHOW tables;", [], (error, rows, fields) => {
resolve({ fields, rows });
});
});
});
// Return result as JSON
return new Response(JSON.stringify(result), {
headers: {
"Content-Type": "application/json",
},
});
},
} satisfies ExportedHandler<Env>;要识别 Hyperdrive 到 MySQL 数据库服务器的活动连接:
- Hyperdrive 到数据库的连接在
performance_schema.threads表的PROGRAM_NAME列中显示为Cloudflare Hyperdrive。 - 运行
SELECT DISTINCT USER, HOST, PROGRAM_NAME FROM performance_schema.threads WHERE PROGRAM_NAME = 'Cloudflare Hyperdrive'可查看 Hyperdrive 是否当前保持到数据库的连接。
- 请参阅支持的数据库集成列表,了解连接现有数据库的其他方式。
- 了解更多如何在 Worker 中使用 Socket API。
- 了解 Workers 支持的协议。