跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

ClickHouse Managed Postgres

Connect Hyperdrive to ClickHouse Managed Postgres.

最后更新 查看 MarkdownAgent 设置

此示例将 Hyperdrive 连接到 ClickHouse Cloud 中的 ClickHouse Managed Postgres ↗ 数据库。ClickHouse Managed Postgres 是一项托管 PostgreSQL 服务,具有本地 NVMe 存储,并内置 ClickHouse 分析集成。

先决条件

开始之前,你需要准备:

  • 一个现有的 ClickHouse Managed Postgres 实例。
  • 一个 Workers 项目。请参阅快速入门以创建项目。
  • 已通过 Cloudflare 账户进行身份验证的 Wrangler 版本 4.9.0 或更高版本。

1. 获取连接详细信息

  1. 在 ClickHouse Cloud 控制台 ↗中,选择你的 Postgres 实例并打开 Connect 菜单。
  2. 选择 Directly 以使用直接 PostgreSQL 端点。Hyperdrive 提供连接池。
  3. 复制主机名、端口、数据库名称、用户名和密码。请使用具有应用程序所需权限的数据库角色。
  4. 在 Settings 中下载此实例的证书颁发机构 (CA) 证书,并在本地将其保存为 postgres-ca.pem。

更多信息请参阅 ClickHouse Managed Postgres 连接详细信息 ↗。

你的数据库必须允许来自 Hyperdrive 的连接。如果你按 IP 地址限制入站连接,请允许Cloudflare IP 地址范围。

2. 创建数据库配置

使用实例 CA 通过传输层安全协议 (TLS) 验证数据库服务器。该 CA 证书专用于你的 Postgres 实例。

  1. 将 CA 证书上传到你的 Cloudflare 账户:

    npx wrangler cert upload certificate-authority --ca-cert postgres-ca.pem --name clickhouse-postgres-ca
  2. 从命令输出中复制证书 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-disabled

    将每个占位符替换为你的值。使用直接端点端口,默认值为 5432。请妥善保管密码和命令输出。

  3. 从输出中复制 Hyperdrive 配置 ID。在下一部分中,将此 ID 用于 Worker 绑定。

verify-full 模式会验证证书和数据库主机名。创建配置时,Hyperdrive 会检查连接。有关证书配置详情,请参阅 SSL/TLS 证书。

此示例会关闭查询缓存,使读取请求直接访问 Postgres。连接池仍然适用。对于可以接受缓存结果的工作负载,请参阅查询缓存。

3. 在 Worker 中使用 Hyperdrive

安装 node-postgres 驱动:

npm i pg@>8.16.3

若使用 TypeScript,安装类型包:

npm i -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 和查询结果。

后续步骤

这篇文档对您有帮助吗?