用 Hyperdrive 讓 Worker 連既有的 Postgres

你已經有一個區域型 Postgres 在跑——可能在 Neon、Supabase、AWS RDS，或你自己的伺服器上。它只住在一個地方。但你的 Workers 卻跑在數百個城市裡。這篇教學會用 Hyperdrive 把 Worker 接到那個資料庫，讓每個請求都能重複利用已經接通的連線、並從快取讀資料，而不是每次都付完整的延遲成本。

Hyperdrive 夾在中間，同時扮演「連線池（connection pooler，把連線存起來共用的中介）」和「查詢快取（query cache，把查詢結果記起來）」。你的程式碼照樣用一般的 Postgres 驅動程式——唯一的差別是它連到的是 env.HYPERDRIVE.connectionString，而不是資料庫真正的網址。

下面這張圖把同一份工作畫了兩次。上半部直接連線、每次請求都重建一條連線；下半部走 Hyperdrive，重複利用已接通、進到連線池的連線——常常直接從快取回答。

五個步驟：建立一個指向你資料庫的 Hyperdrive 設定、把綁定加進 wrangler.toml、安裝 Postgres 驅動程式、透過 env.HYPERDRIVE.connectionString 查詢，然後部署。

1. 建立 Hyperdrive 設定

   把你既有的連線字串交給 Hyperdrive。Wrangler 會印出一組 id——複製起來下一步要用。

   bashcontent_copy複製

   npx wrangler hyperdrive create my-postgres \
     --connection-string="postgres://user:password@db.example.com:5432/appdb"

2. 加入 [[hyperdrive]] 綁定

   把 id 貼進 wrangler.toml。一定要開 nodejs_compat 旗標，因為 Postgres 驅動程式會用到 Node 的 API。

   tomlcontent_copy複製

   name = "my-worker"
   main = "src/index.js"
   compatibility_date = "2024-09-23"
   compatibility_flags = ["nodejs_compat"]
   
   [[hyperdrive]]
   binding = "HYPERDRIVE"
   id = "<paste-the-id-from-step-1>"

3. 安裝 Postgres 驅動程式

   這裡用 postgres.js；node-postgres 的 pg 套件也可以。

   bashcontent_copy複製

   npm i postgres

4. 透過 Hyperdrive 查詢

   連到 env.HYPERDRIVE.connectionString——絕對不是資料庫真正的網址。每個 isolate 維持一個小連線池，並在背景關閉它。

   jscontent_copy複製

   import postgres from "postgres";
   
   export default {
     async fetch(request, env, ctx) {
       // Connect to Hyperdrive, not the database directly
       const sql = postgres(env.HYPERDRIVE.connectionString, {
         max: 5,            // small pool per Worker isolate
         fetch_types: false // skip an extra round-trip
       });
   
       try {
         const products = await sql`SELECT id, name, price FROM products LIMIT 10`;
         // Close in the background so it does not delay the response
         ctx.waitUntil(sql.end());
         return Response.json(products);
       } catch (err) {
         console.error(err);
         return Response.json({ error: String(err) }, { status: 500 });
       }
     }
   };

5. 部署上線

   發布 Worker。查詢就會走上有連線池、有快取的快速通道了。

   bashcontent_copy複製

   npx wrangler deploy

安全地讀取與寫入

// Parameterized values are sent separately, never string-concatenated
const id = 42;
const rows = await sql`SELECT id, name FROM products WHERE id = ${id}`;

// Writes (INSERT/UPDATE/DELETE) are never cached — they always hit Postgres
await sql`INSERT INTO views (product_id) VALUES (${id})`;

• 沒有 compatibility_flags = ["nodejs_compat"] 和夠新的 compatibility_date，Postgres 驅動程式會載入失敗。
• 只有唯讀的 SELECT 會被快取；INSERT／UPDATE／DELETE 一定會到 Postgres。
• 用到 NOW()、RANDOM()、CURRENT_DATE 的查詢會被視為不可快取——甚至只在 SQL 註解裡提到這些函式名稱，也會讓那筆查詢不快取。
• 一律用 ctx.waitUntil(sql.end()) 收尾，清理才不會拖慢回應。
• 每個 isolate 的連線池維持小一點（例如 max: 5）；Hyperdrive 反正會在背後多工共用。
• 支援 Postgres 與相容資料庫（Neon、Supabase、RDS、CockroachDB、Timescale）——也支援 MySQL。
• 想要 Cloudflare 原生的 SQL 資料庫、而不是自備？可以看看 D1。