本示例展示如何将 Hyperdrive 连接到 Digital Ocean 数据库实例。
要允许 Hyperdrive 连接数据库，需确保 Hyperdrive 拥有有效用户凭据和网络访问权限。
- 前往 DigitalOcean 仪表板并选择要连接的数据库。
- 前往 Overview（概览） 选项卡。
- 在 Connection Details（连接详情） 面板下，选择 Public network（公共网络）。
- 在下拉菜单中选择 Connection string（连接字符串） > show-password（显示密码）。
- 复制连接字符串。
有了连接字符串后，即可创建 Hyperdrive 数据库配置。
配置 Hyperdrive 需要：
- 数据库的 IP 地址（或主机名）和端口。
- 上一步配置的数据库用户名（例如
hyperdrive-demo）。 - 该用户名对应的密码。
- 希望 Hyperdrive 连接的数据库名称，例如
postgres。
Hyperdrive 接受数据库驱动常用的连接字符串格式组合上述参数：
postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name大多数数据库提供商会提供可直接复制到 Hyperdrive 的连接字符串。
在 Cloudflare 仪表板中创建 Hyperdrive 配置：
-
在 Cloudflare 仪表板中，前往 Hyperdrive 页面。
Go to Hyperdrive ↗ -
选择 Create Configuration（创建配置）。
-
填写表单，包括连接字符串。
-
选择 Create（创建）。
使用 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="postgres://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>"
安装 node-postgres 驱动：
npm i pg@>8.16.3yarn add pg@>8.16.3pnpm add pg@>8.16.3bun add pg@>8.16.3若使用 TypeScript，安装类型包：
npm i -D @types/pgyarn add -D @types/pgpnpm add -D @types/pgbun add -d @types/pg在 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>"创建新的 Client 实例并传入 Hyperdrive connectionString：
// filepath: src/index.ts
import { Client } from "pg";
export default {
async fetch(
request: Request,
env: Env,
ctx: ExecutionContext,
): Promise<Response> {
// Create a new client instance for each request. Hyperdrive maintains the
// underlying database connection pool, so creating a new client is fast.
const client = new Client({
connectionString: env.HYPERDRIVE.connectionString,
});
try {
// Connect to the database
await client.connect();
// Perform a simple query
const result = await client.query("SELECT * FROM pg_tables");
return Response.json({
success: true,
result: result.rows,
});
} catch (error: any) {
console.error("Database error:", error.message);
return new Response("Internal error occurred", { status: 500 });
}
},
};- 了解更多 Hyperdrive 工作原理。
- 参阅故障排除指南以排查常见问题。
- 进一步了解 Cloudflare Workers 可用的其他存储选项。