Cloudflare Python Workers 怎麼接 Hyperdrive？PostgreSQL 與 MySQL 的設定邊界

先確認 Beta 的適用條件#

官方 Python Hyperdrive 文件列出的基本邊界是：

• compatibility date 要是 2026-09-08 或更新版本。
• Wrangler 設定要加入 python_workers compatibility flag。
• 目前可連 PostgreSQL 與 MySQL。
• 官方文件建議使用支援的 Python database driver，再透過 Hyperdrive binding 取得連線設定。
• Python Workers 透過 TCP socket API 連線；同步操作需要鎖定以序列化存取。
• 目前只有同步 SQLAlchemy，async SQLAlchemy 因為依賴 greenlet 而不支援。

這些條件不是部署後才處理的微調，而是選型門檻。如果你的應用程式依賴 async SQLAlchemy、需要大量同步資料庫操作，或必須使用尚未確認支援的 driver，先做小型 PoC，別直接搬整個 production service。

Wrangler 設定 Hyperdrive binding#

以下是 JSONC 設定的最小方向；HYPERDRIVE 是程式碼裡要使用的 binding 名稱，id 必須換成你在 Cloudflare 建立的 Hyperdrive config ID：

1
{
2
  "name": "python-hyperdrive-worker",
3
  "main": "src/entry.py",
4
  "compatibility_date": "2026-09-20",
5
  "compatibility_flags": ["python_workers"],
6
  "hyperdrive": [
7
    {
8
      "binding": "HYPERDRIVE",
9
      "id": "replace-with-hyperdrive-config-id"
10
    }
11
  ]
12
}

這段設定使用目前日期只是示意，重點是不能早於 Python Hyperdrive 文件要求的 compatibility date。實際部署前，請確認專案的 Wrangler 版本、Hyperdrive config ID、資料庫網路可達性與 secrets 都已分開設定；不要把資料庫密碼寫進 repository。

若專案使用 wrangler.toml，欄位名稱和陣列語法會不同，但要表達相同的 compatibility_date、compatibility_flags 與 Hyperdrive binding。完成後先用本地開發命令確認打包結果，再部署：

1
uv run pywrangler dev
2
uv run pywrangler deploy

這裡的命令是官方部署流程的寫法，不代表本次排程已替你的 Cloudflare 帳號執行；本次沒有進行 live Worker、資料庫或 migration 測試。

依資料庫選 driver 與依賴#

官方範例目前建議的 driver 可以整理成這樣：

例如 pyproject.toml 可以先只加入一種目標資料庫 driver：

1
[project]
2
dependencies = [
3
  "asyncpg",
4
]

不要把表格中的所有 driver 都安裝進 Worker 來「增加相容性」。這會擴大 bundle、引入不必要的依賴，也讓真正使用哪一個 driver 變得不清楚。依官方範例選一個最符合資料庫與程式模型的 driver，再用最小 query 驗證。

PostgreSQL 的最小連線流程#

Python Worker 會從 Hyperdrive binding 取得 connection string，再交給 driver。概念上的 asyncpg 寫法如下：

1
from workers import WorkerEntrypoint, Response
2
import asyncpg
3

4

5
class Default(WorkerEntrypoint):
6
    async def fetch(self, request):
7
        connection = await asyncpg.connect(
8
            self.env.HYPERDRIVE.connectionString,
9
            ssl=False,
10
        )
11
        try:
12
            row = await connection.fetchrow("SELECT 1 AS ok")
13
            return Response.json({"ok": row["ok"]})
14
        finally:
15
            await connection.close()

實際專案要依官方 Python Workers runtime、driver 版本與你的 entrypoint 形狀調整。這裡的 SELECT 1 只能確認最小連線路徑，不能證明 transaction、pool、query timeout、migration 或權限模型都適用。不要把這段示意程式當成已在本機或 production 執行過的測試。

MySQL 的最小連線流程#

MySQL 可以依官方範例評估 aiomysql 或 pymysql。以 async driver 的概念寫法來說，重點是傳入 Hyperdrive 提供的連線參數，並在 request 結束前釋放連線：

1
import aiomysql
2
from workers import WorkerEntrypoint, Response
3

4

5
class Default(WorkerEntrypoint):
6
    async def fetch(self, request):
7
        connection = await aiomysql.connect(
8
            host=self.env.HYPERDRIVE.host,
9
            port=self.env.HYPERDRIVE.port,
10
            user=self.env.HYPERDRIVE.user,
11
            password=self.env.HYPERDRIVE.password,
12
            db=self.env.HYPERDRIVE.database,
13
            ssl=None,
14
        )
15
        try:
16
            async with connection.cursor() as cursor:
17
                await cursor.execute("SELECT 1 AS ok")
18
                row = await cursor.fetchone()
19
            return Response.json({"ok": row[0]})
20
        finally:
21
            connection.close()

不同版本的 driver、Workers Python runtime 和 Hyperdrive 文件可能要求不同的連線欄位或 SSL 處理；上例是閱讀官方範例後整理的結構，不是本次執行的實測程式。部署前應把官方範例與你安裝的 driver 版本逐欄比對，並在測試資料庫驗證連線關閉、錯誤處理和權限。

SQLAlchemy、socket 與同步操作的限制#

Python Hyperdrive 最容易被誤解的地方，是「能連資料庫」不等於所有 Python database stack 都已可用：

上線前的最小驗證矩陣#

在把原本的應用程式搬到 Python Worker 前，至少完成以下驗證：

1. 用 uv run pywrangler dev 確認 bundle 可以建立，且只包含真正需要的 driver。
2. 在測試資料庫執行一個 read query、parameterized write 和 transaction rollback。
3. 模擬資料庫拒絕、逾時、連線關閉與 Worker request 取消。
4. 分別驗證單一 request、並行 request 和冷啟動，不把一次成功的 SELECT 1 當成 pool 正常。
5. 若使用 SQLAlchemy，確認是同步路徑，並把 session、transaction 和 lock 的生命週期寫進測試。
6. 確認 Hyperdrive、資料庫與 Worker 的權限最小化，且 log 不會輸出 connection string。
7. 再用 uv run pywrangler deploy 部署到非 production 環境，觀察實際 latency、錯誤率與資料庫連線數。

這次排程只建立指南，沒有替你完成第 2 至 7 項的 live 驗證。這個限制很重要：Cloudflare 文件支援的是整合路徑，不是對你的 driver 版本、schema、query 和流量模型做保證。

常見問題#