此示例将 Hyperdrive 连接到 ClickHouse Cloud 中的 ClickHouse Managed Postgres ↗ 数据库。ClickHouse Managed Postgres 是一项托管 PostgreSQL 服务,具有本地 NVMe 存储,并内置 ClickHouse 分析集成。
开始之前,你需要准备:
- 一个现有的 ClickHouse Managed Postgres 实例。
- 一个 Workers 项目。请参阅快速入门以创建项目。
- 已通过 Cloudflare 账户进行身份验证的 Wrangler 版本
4.9.0或更高版本。
- 在 ClickHouse Cloud 控制台 ↗中,选择你的 Postgres 实例并打开 Connect 菜单。
- 选择 Directly 以使用直接 PostgreSQL 端点。Hyperdrive 提供连接池。
- 复制主机名、端口、数据库名称、用户名和密码。请使用具有应用程序所需权限的数据库角色。
- 在 Settings 中下载此实例的证书颁发机构 (CA) 证书,并在本地将其保存为
postgres-ca.pem。
更多信息请参阅 ClickHouse Managed Postgres 连接详细信息 ↗。
你的数据库必须允许来自 Hyperdrive 的连接。如果你按 IP 地址限制入站连接,请允许Cloudflare IP 地址范围。
使用实例 CA 通过传输层安全协议 (TLS) 验证数据库服务器。该 CA 证书专用于你的 Postgres 实例。
-
将 CA 证书上传到你的 Cloudflare 账户:
npx wrangler cert upload certificate-authority --ca-cert postgres-ca.pem --name clickhouse-postgres-cayarn wrangler cert upload certificate-authority --ca-cert postgres-ca.pem --name clickhouse-postgres-capnpm wrangler cert upload certificate-authority --ca-cert postgres-ca.pem --name clickhouse-postgres-ca -
从命令输出中复制证书 ID。使用此 ID 和数据库连接详细信息创建 Hyperdrive 配置:
npx wrangler hyperdrive create clickhouse-postgres --origin-host '<HOSTNAME>' --origin-port '<PORT>' --database '<DATABASE_NAME>' --origin-scheme postgres --origin-user '<USERNAME>' --origin-password '<PASSWORD>' --ca-certificate-id '<CA_CERTIFICATE_ID>' --sslmode verify-full --caching-disabledyarn wrangler hyperdrive create clickhouse-postgres --origin-host '<HOSTNAME>' --origin-port '<PORT>' --database '<DATABASE_NAME>' --origin-scheme postgres --origin-user '<USERNAME>' --origin-password '<PASSWORD>' --ca-certificate-id '<CA_CERTIFICATE_ID>' --sslmode verify-full --caching-disabledpnpm wrangler hyperdrive create clickhouse-postgres --origin-host '<HOSTNAME>' --origin-port '<PORT>' --database '<DATABASE_NAME>' --origin-scheme postgres --origin-user '<USERNAME>' --origin-password '<PASSWORD>' --ca-certificate-id '<CA_CERTIFICATE_ID>' --sslmode verify-full --caching-disabled将每个占位符替换为你的值。使用直接端点端口,默认值为
5432。请妥善保管密码和命令输出。 -
从输出中复制 Hyperdrive 配置 ID。在下一部分中,将此 ID 用于 Worker 绑定。
verify-full 模式会验证证书和数据库主机名。创建配置时,Hyperdrive 会检查连接。有关证书配置详情,请参阅 SSL/TLS 证书。
此示例会关闭查询缓存,使读取请求直接访问 Postgres。连接池仍然适用。对于可以接受缓存结果的工作负载,请参阅查询缓存。
安装 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-11-14",
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "<your-hyperdrive-id-here>"
}
]
}compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-11-14"
[[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 建立的连接,请部署 Worker并访问其 URL。成功的响应包含 success: true 和查询结果。
- 配置本地开发。
- 查看支持的 PostgreSQL 功能。
- 通过故障排查和调试诊断连接错误。