Cloudflare Hyperdrive MySQL 怎麼接？用 mysql2 設定 Workers binding

Hyperdrive MySQL 先分清楚三個責任#

這個分工也解釋了為什麼「binding 已經出現在 Wrangler 輸出」不代表查詢一定成功。仍要檢查 MySQL 使用者權限、TLS、來源網路與查詢本身。

建立 Hyperdrive 並取得 binding ID#

先用 Wrangler 建立一個 Hyperdrive 設定。官方命令會使用 MySQL connection string 建立連線設定：

1
npx wrangler hyperdrive create my-mysql --connection-string="mysql://USER:[email protected]:3306/app"

這個指令需要能連到資料庫的帳號。不要把真實 connection string 寫進 shell history、shell script 或 commit；如果團隊已經有平台化的建立流程，改用 Cloudflare Dashboard 或 API 管理建立時的憑證輸入。指令輸出的 Hyperdrive ID 才需要放進 Wrangler 設定檔。

Wrangler 設定要留下兩個關鍵欄位#

把 binding 放在 Worker 專案的 wrangler.jsonc。Cloudflare 的 MySQL 範例要求使用 Node.js compatibility，mysql2 也要在 Worker 執行環境使用相容模式：

1
{
2
  "$schema": "./node_modules/wrangler/config-schema.json",
3
  "name": "mysql-worker",
4
  "main": "./src/index.ts",
5
  "compatibility_date": "2026-08-20",
6
  "compatibility_flags": [
7
    "nodejs_compat"
8
  ],
9
  "hyperdrive": [
10
    {
11
      "binding": "HYPERDRIVE",
12
      "id": "<your-hyperdrive-id>"
13
    }
14
  ]
15
}

2026-08-04 之後的新 compatibility date 會涵蓋部分 Node.js compatibility 行為，但不要把「平台預設已改變」誤當成「既有專案可以不測試就刪 flag」。先保留設定，等測試完成後再依 compatibility_date 升級清單決定是否清理。

接著安裝官方文件指定的最低版本：

1
pnpm add mysql2@'>=3.13.0'

用 mysql2/promise 查詢 MySQL#

最小的 Worker 可以這樣寫：

1
import { createConnection } from "mysql2/promise";
2

3
export default {
4
  async fetch(_request: Request, env: Env): Promise<Response> {
5
    const connection = await createConnection({
6
      host: env.HYPERDRIVE.host,
7
      user: env.HYPERDRIVE.user,
8
      password: env.HYPERDRIVE.password,
9
      database: env.HYPERDRIVE.database,
10
      port: env.HYPERDRIVE.port,
11
      disableEval: true,
12
    });
13

14
    try {
15
      const [rows] = await connection.query(
16
        "SELECT id, name FROM users ORDER BY id DESC LIMIT 10",
17
      );
18

19
      return Response.json({ rows });
20
    } catch (error) {
21
      console.error(error);
22
      return Response.json({ error: "database query failed" }, { status: 500 });
23
    }
24
  },
25
} satisfies ExportedHandler<Env>;

這裡刻意每次 request 建立一個 connection，因為 Hyperdrive 會處理底層的資料庫連線池；不要把連線物件放在 module global，然後假設它能跨越所有 Worker invocation 永遠有效。disableEval: true 不是一般 MySQL 的通用設定，而是 Cloudflare 文件對 mysql2 在 Workers 的要求。

如果 TypeScript 還沒有自動產生 Env 型別，可以先用 Wrangler 產生：

1
npx wrangler types

本機 wrangler dev 不會走 Hyperdrive#

這是最容易把測試結果看錯的地方。預設的 wrangler dev 會在本機執行 Worker，並直接連到 localConnectionString 指定的資料庫；這個模式不會啟用 Hyperdrive 的連線池與 query caching。

建議用環境變數提供本機連線字串，避免把密碼寫進 wrangler.jsonc：

1
export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="mysql://USER:[email protected]:3306/app?sslMode=required"
2
npx wrangler dev

若要測試實際 Hyperdrive 行為，才使用：

1
npx wrangler dev --remote

--remote 會在 Cloudflare 網路執行 Worker，使用已部署的 Hyperdrive 設定；本機程式的寫入與副作用可能碰到遠端資料庫。先準備測試資料庫或唯讀帳號，再用遠端模式驗證 pooling、快取與實際網路路徑。

上線前用四層檢查找錯#

1. Binding：wrangler deploy --dry-run 是否讀到正確的 HYPERDRIVE ID，env.HYPERDRIVE 是否有 host、port 與 database。
2. Driver：mysql2 是否至少為 3.13.0，並保留 disableEval: true 與必要的 Node.js compatibility。
3. 資料庫入口：MySQL 帳號是否允許 Hyperdrive 連線、TLS 模式是否符合資料庫要求、SELECT／INSERT 權限是否足夠。
4. 測試模式：本機 dev 測到的是 direct connection；要檢查 Hyperdrive 的 pooling 或 query cache，必須用隔離的遠端環境，不要把 production 當成測試資料庫。

如果查詢本身成功，但延遲或資料內容不符合預期，先把「本機 direct connection」與「遠端 Hyperdrive connection」分開比較。這比只換 driver 或反覆重建 binding 更容易定位問題。

結論：先把連線路徑說清楚，再決定要不要快取#

Hyperdrive MySQL 的最小可用組合是：HYPERDRIVE binding、[email protected] 以上、Workers 的 Node.js compatibility，以及 disableEval: true。本機開發使用 localConnectionString 時，測的是直接連資料庫；只有 wrangler dev --remote 或正式部署才會驗證 Hyperdrive 的連線池與快取。