本示例展示如何将 Hyperdrive 连接到 Supabase ↗ Postgres 数据库。
可将 Hyperdrive 连接到任何现有 Supabase 数据库，使用项目创建时设置的 Postgres 用户。 或者，为 Hyperdrive 创建新用户时，在 SQL Editor ↗ 中运行以下命令。
CREATE ROLE hyperdrive_user LOGIN PASSWORD 'sufficientlyRandomPassword';
-- Here, you are granting it the postgres role. In practice, you want to create a role with lesser privileges.
GRANT postgres to hyperdrive_user;数据库端点可在数据库设置页面 ↗找到。
有了数据库用户、密码、数据库端点（主机名和端口）和数据库名称（默认：postgres）后，即可设置 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 可用的其他存储选项。