本示例展示如何将 Hyperdrive 连接到 Timescale ↗ 时序数据库。Timescale 基于 PostgreSQL 构建，包含强大的时序、事件和分析功能。
可通过 Timescale 服务文档 ↗ 了解更多 Timescale 信息。
通过创建新用户并获取数据库连接字符串，可将 Hyperdrive 连接到任何现有 Timescale 数据库。
在 Timescale Console ↗ 中获取凭据和数据库端点：
- 选择希望 Hyperdrive 连接的服务（数据库）。
- 展开 Connection info（连接信息）。
- 复制 Service URL（服务 URL）。Service URL 是 Hyperdrive 用于连接的连接字符串，包含数据库主机名、端口号和数据库名称。
若未存储密码，需选择 Forgot your password?（忘记密码？） 并设置新的 SCRAM 密码。请保存此密码，Timescale 仅显示一次。
最终会得到类似以下的连接字符串：
postgres://tsdbadmin:YOUR_PASSWORD_HERE@pn79dztyy0.xzhhbfensb.tsdb.cloud.timescale.com:31358/tsdb有了连接字符串后，即可创建 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 可用的其他存储选项。