Neon

要使用 Hyperdrive 连接 Neon，请按以下步骤操作：

通过创建新用户并获取数据库连接字符串，可将 Hyperdrive 连接到任何现有 Neon 数据库。

1. 前往 Neon 仪表板 ↗ 并选择要连接的项目（数据库）。
2. 在侧边栏选择 Roles（角色），再选择 New Role（新角色）。输入 hyperdrive-user 作为名称（或你偏好的名称）并复制密码。密码不会再次显示：若未保存需重置。
3. 在侧边栏选择 Dashboard（仪表板） > 进入 Connection Details（连接详情） 面板 > 确保已选择 Hyperdrive 将连接的 branch（分支）、database（数据库） 和 role（例如 hyperdrive-user）。
4. 选择 psql 并取消勾选 connection pooling 复选框。从文本框记下连接字符串（以 postgres://hyperdrive-user@... 开头）。

有了连接字符串和密码后，即可创建 Hyperdrive 数据库配置。

配置 Hyperdrive 需要：

• 数据库的 IP 地址（或主机名）和端口。
• 上一步配置的数据库用户名（例如 hyperdrive-demo）。
• 该用户名对应的密码。
• 希望 Hyperdrive 连接的数据库名称，例如 postgres。

Hyperdrive 接受数据库驱动常用的连接字符串格式组合上述参数：

postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

大多数数据库提供商会提供可直接复制到 Hyperdrive 的连接字符串。

安装 node-postgres 驱动：

npm i pg@>8.16.3

yarn add pg@>8.16.3

pnpm add pg@>8.16.3

bun add pg@>8.16.3

若使用 TypeScript，安装类型包：

npm i -D @types/pg

yarn add -D @types/pg

pnpm add -D @types/pg

bun 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 可用的其他存储选项。

要使用 @neondatabase/serverless 连接 Neon，请按以下步骤操作：

1. 你需要有一个现有的 Neon 数据库可供连接。创建 Neon 数据库 ↗ 或从现有数据库加载数据到 Neon ↗。

2. 使用 Neon SQL 编辑器创建 elements 表。SQL 编辑器允许你直接从 Neon 控制台查询数据库。

   CREATE TABLE elements (
     id INTEGER NOT NULL,
     elementName TEXT NOT NULL,
     atomicNumber INTEGER NOT NULL,
     symbol TEXT NOT NULL
   );

3. 在新创建的表中插入一些数据。

   INSERT INTO elements (id, elementName, atomicNumber, symbol)
   VALUES
     (1, 'Hydrogen', 1, 'H'),
     (2, 'Helium', 2, 'He'),
     (3, 'Lithium', 3, 'Li'),
     (4, 'Beryllium', 4, 'Be'),
     (5, 'Boron', 5, 'B'),
     (6, 'Carbon', 6, 'C'),
     (7, 'Nitrogen', 7, 'N'),
     (8, 'Oxygen', 8, 'O'),
     (9, 'Fluorine', 9, 'F'),
     (10, 'Neon', 10, 'Ne');

4. 在 Worker 中配置 Neon 数据库凭据：

   你需要将 Neon 数据库连接字符串作为 secret 添加到 Worker。从 Neon 控制台 ↗ 的 Connection Details（连接详情） 下获取连接字符串，然后使用 Wrangler 添加为 secret：

   # Add the database connection string as a secret
   npx wrangler secret put DATABASE_URL
   # When prompted, paste your Neon database connection string

5. 在 Worker 中安装 @neondatabase/serverless 驱动以连接数据库并开始操作数据：

   npmyarnpnpmbun

   npm i @neondatabase/serverless

6. 以下示例展示如何在 Worker 中查询 Neon 数据库。连接 Neon 所需的凭据已作为 secret 添加到 Worker。

   import { Client } from "@neondatabase/serverless";
   
   export default {
   	async fetch(request, env, ctx) {
   		const client = new Client(env.DATABASE_URL);
   		await client.connect();
   		const { rows } = await client.query("SELECT * FROM elements");
   
   		return new Response(JSON.stringify(rows));
   	},
   };

要了解更多关于 Neon 的信息，请参阅 Neon 官方文档 ↗。