Workers 连接 Neon：Hyperdrive 首选，serverless driver 备选

Neon 官方推荐用 Hyperdrive 池化连接；轻量场景可用 @neondatabase/serverless 走 HTTP 或 WebSocket。

INTEGRATIONS进阶30 分钟最后核验：2026-08-27

先给结论

官方推荐路径是 Hyperdrive：边缘连接池能摊掉 Neon compute 冷启动与 TLS 握手成本。查询频率低、不想维护 Hyperdrive 配置时，可用 @neondatabase/serverless 走 HTTP 或 WebSocket。

两条路径怎么选

路径	适合	关键限制
Hyperdrive + Postgres driver	高频查询、延迟敏感、已有 Postgres 工具链	需要专用 role 与非池化连接串；不支持 LISTEN/NOTIFY 等特性
`@neondatabase/serverless`	低频读写、原型、不想多一层配置	每次请求自付握手；scale-to-zero 后首查有数百毫秒冷启动

Neon 免费计划的 compute 闲置约 5 分钟后 scale-to-zero，冷启动需数百毫秒。Hyperdrive 的连接池能掩盖大部分影响，HTTP driver 路径则每次冷启动都要付这笔延迟。

路径一：Hyperdrive（推荐）

在 Neon Dashboard 为 Worker 新建一个专用 role（不要复用 owner 账号），然后在连接详情里取消勾选 connection pooling——Hyperdrive 自己做池化，再用 Neon 的池化地址会叠加两层池。拿到的连接串形如 postgres://<role>:<password>@<host>/<db>?sslmode=require。

npx wrangler hyperdrive create neon-pg --connection-string="postgres://<role>:<password>@<host>/<db>?sslmode=require"

wrangler.jsonc

{
  "name": "notes-api",
  "compatibility_date": "2026-08-25",
  "compatibility_flags": ["nodejs_compat"],
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<创建命令返回的 id>" }
  ]
}

src/index.ts

import { Client } from 'pg';

interface Env {
  HYPERDRIVE: Hyperdrive;
}

export default {
  async fetch(request, env: Env): Promise<Response> {
    const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
    try {
      await client.connect();
      const result = await client.query('SELECT id, title FROM notes LIMIT 10');
      return Response.json({ notes: result.rows });
    } catch (error) {
      return Response.json({ error: String(error) }, { status: 502 });
    } finally {
      await client.end().catch(() => {});
    }
  },
};

路径二：@neondatabase/serverless

npm i @neondatabase/serverless
npx wrangler secret put DATABASE_URL

DATABASE_URL 是 Neon Dashboard 里的完整连接串。该包默认走 HTTP 单次查询，也可用 WebSocket 维持会话。

src/index.ts

import { neon } from '@neondatabase/serverless';

interface Env {
  DATABASE_URL: string;
}

export default {
  async fetch(request, env: Env): Promise<Response> {
    const sql = neon(env.DATABASE_URL);
    try {
      const rows = await sql`SELECT id, title FROM notes LIMIT 10`;
      return Response.json({ notes: rows });
    } catch (error) {
      return Response.json({ error: String(error) }, { status: 502 });
    }
  },
};

验证与排障

curl -s https://<worker>.workers.dev/notes

现象	先检查	恢复动作
首查延迟数百毫秒后正常	compute 是否刚从 scale-to-zero 唤醒	接受延迟，或迁移到 Hyperdrive 路径
Hyperdrive 路径报认证失败	是否用了 owner 账号或池化连接串	换专用 role 与非池化串重建 Hyperdrive
`password authentication failed`	连接串里的密码是否含需转义字符	重新复制连接串，必要时 URL 编码
SQL 报不支持的特性	是否用了 LISTEN/NOTIFY 或 advisory locks	改写为轮询或队列方案

创建 Hyperdrive 配置、写入 DATABASE_URL Secret、在 Neon 新建 role 都会修改远程状态，本教程不自动执行。回滚时：先在 wrangler.jsonc 删除 hyperdrive 绑定并重新部署，再 wrangler hyperdrive delete <id> 删除配置；随后轮换 Neon 侧的 role 密码或直接删除专用 role，最后在 Cloudflare 侧删除不再使用的 Secret。数据库数据本身不受代码回滚影响。

下一步：Workers 连接 Turso；上线后的监控接入见可观测性。

Workers 连接 Neon：Hyperdrive 首选，serverless driver 备选

两条路径怎么选

路径一：Hyperdrive（推荐）

路径二：@neondatabase/serverless

验证与排障

远程边界与回滚

官方来源

这篇内容帮你完成目标了吗？

本页目录