Supabase

要设置 Supabase 集成：

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

2. 使用以下查询创建 countries 表。你可以在 Supabase 仪表板中通过两种方式创建表：

   • 使用表编辑器，它允许你像电子表格一样设置 Postgres。
   • 或者，使用 SQL 编辑器 ↗：

   CREATE TABLE countries (
   id SERIAL PRIMARY KEY,
   name VARCHAR(255) NOT NULL
   );

3. 在新创建的表中插入一些数据。运行以下命令向表中添加国家：

   INSERT INTO countries (name) VALUES ('United States');
   INSERT INTO countries (name) VALUES ('Canada');
   INSERT INTO countries (name) VALUES ('The Netherlands');

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

   你需要将 Supabase URL 和 anon 密钥作为 secret 添加到 Worker。从 Supabase 仪表板 ↗ 的 Settings（设置） > API 下获取这些值，然后使用 Wrangler 添加为 secret：

   # Add the Supabase URL as a secret
   npx wrangler secret put SUPABASE_URL
   # When prompted, paste your Supabase project URL
   
   # Add the Supabase anon key as a secret
   npx wrangler secret put SUPABASE_KEY
   # When prompted, paste your Supabase anon/public key

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

   npmyarnpnpmbun

   npm i @supabase/supabase-js

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

   import { createClient } from "@supabase/supabase-js";
   
   export default {
   	async fetch(request, env) {
   		const supabase = createClient(env.SUPABASE_URL, env.SUPABASE_KEY);
   		const { data, error } = await supabase.from("countries").select("*");
   		if (error) throw error;
   		return new Response(JSON.stringify(data), {
   			headers: {
   				"Content-Type": "application/json",
   			},
   		});
   	},
   };

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

使用 Hyperdrive 连接 Supabase 时，你直接连接到底层 Postgres 数据库。这从 Workers 服务端访问时可为数据库查询提供最低延迟。要使用 Hyperdrive 连接 Supabase，请按以下步骤操作：

Hyperdrive 可连接到任何现有 Supabase 数据库，使用项目创建时设置的 Postgres 用户。 或者，为 Hyperdrive 创建新用户时，在 SQL Editor ↗ 中运行以下命令。

数据库端点可在数据库设置页面 ↗找到。

有了数据库用户、密码、数据库端点（主机名和端口）和数据库名称（默认：postgres）后，即可设置 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 可用的其他存储选项。