跳转到内容
搜索文档

连接 MySQL

最后更新 查看 MarkdownAgent 设置

Hyperdrive 支持 MySQL 及 MySQL 兼容数据库、常用驱动以及使用这些驱动的对象关系映射(ORM)库。

创建 Hyperdrive

要创建连接现有 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 也可能受支持:此列表并非详尽。

数据库驱动与 Node.js 兼容性

数据库驱动(包括 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"

支持的 TLS (SSL) 模式

连接源数据库时,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_CAVERIFY_IDENTITY TLS (SSL) 模式的详情,请参阅 SSL/TLS 证书 文档。

驱动示例

以下示例展示如何:

  1. 使用数据库驱动创建数据库客户端。
  2. 传入 Hyperdrive 连接字符串并连接数据库。
  3. 通过 Hyperdrive 查询数据库。

mysql2

以下 Workers 代码展示如何使用 mysql2 配合 Hyperdrive 的 Promise API。

安装 mysql2 驱动:

npm i 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>;

mysql

以下 Workers 代码展示如何使用 mysql 配合 Hyperdrive。

安装 mysql 驱动:

npm i 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 的连接

要识别 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 是否当前保持到数据库的连接。

后续步骤

这篇文档对您有帮助吗?