Azure Database 示例

本示例展示如何将 Hyperdrive 连接到 Azure Database for MySQL 实例。

1. 允许 Hyperdrive 访问

要允许 Hyperdrive 连接数据库，需确保 Hyperdrive 拥有有效凭据和网络访问权限。

Azure 门户

公网访问网络

要通过公网连接 Azure Database for MySQL 实例：

在 Azure 门户 ↗ 中，选择希望 Hyperdrive 连接的实例。
展开 Settings（设置） > Networking（网络） > 确保已启用 Public access（公共访问） > 在 Firewall rules（防火墙规则） 中将 Start IP address（起始 IP 地址） 设为 0.0.0.0，End IP address（结束 IP 地址） 设为 255.255.255.255。
选择 Save（保存） 保存更改。
在侧边栏选择 Overview（概览），记下实例的 Server name（服务器名称）。

有了用户名、密码、服务器名称和数据库名称（默认：mysql）后，即可创建 Hyperdrive 数据库配置。

私有访问网络

要连接私有 Azure Database for MySQL 实例，请参阅使用 Tunnel 连接私有数据库。

2. 创建数据库配置

配置 Hyperdrive 需要：

数据库的 IP 地址（或主机名）和端口。
上一步配置的数据库用户名（例如 hyperdrive-demo）。
该用户名对应的密码。
希望 Hyperdrive 连接的数据库名称，例如 mysql。

Hyperdrive 接受数据库驱动常用的连接字符串格式组合上述参数：

mysql://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

大多数数据库提供商会提供可直接复制到 Hyperdrive 的连接字符串。

使用 Wrangler CLI 创建 Hyperdrive 配置时，打开终端并运行以下命令。

将 <NAME_OF_HYPERDRIVE_CONFIG> 替换为 Hyperdrive 配置名称并粘贴数据库主机提供的连接字符串，或
将 user、password、HOSTNAME_OR_IP_ADDRESS、port 和 database_name 占位符替换为你的数据库信息：

npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="mysql://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

该命令会输出 Wrangler 配置文件的绑定：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hyperdrive-example",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "hyperdrive-example"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-17"
compatibility_flags = [ "nodejs_compat" ]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"

3. 从 Worker 使用 Hyperdrive

安装 mysql2 ↗ 驱动：

npm i mysql2@>3.13.0

yarn add mysql2@>3.13.0

pnpm add mysql2@>3.13.0

bun 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>;

后续步骤

了解更多 Hyperdrive 工作原理。
参阅故障排除指南以排查常见问题。
进一步了解 Cloudflare Workers 可用的其他存储选项。