Prisma Next postgresServerless 在 Cloudflare Hyperdrive 后查询挂起怎么排查【免费下载链接】ormNext-generation ORM for Node.js TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB项目地址: https://gitcode.com/GitHub_Trending/pr/orm如果你的 Cloudflare Worker 使用 Prisma Next 的postgresServerless每请求门面访问 Hyperdrive 前置的 Postgres线上读查询长时间无响应、最终请求被 Cloudflare 运行时在 30 秒处杀掉并返回 error 1101而本地wrangler dev和集成测试却一切正常——这就是本文要排查的场景。仓库文档已将该现象定位为 Hyperdrive 侧的协议解析问题并给出了明确的工作方案在postgresServerless({...})传入cursor: { disabled: true }。适用前提部署形态是 Cloudflare Workers Hyperdrive连接串来自env.HYPERDRIVE.connectionString完整示例在 examples/prisma-8-cloudflare-worker。症状判定是否命中 Hyperdrive 的挂起缺陷Serverless Deployment Guide 的 Known limitations 一节的实测结论2026 年 5 月生产 smoke 验证是默认 cursor 路径在真实 Hyperdrive 下会挂起具体表现为——pg-cursor的扩展查询命名 portal 协议中客户端在返回行后发送Close portal SyncHyperdrive 回复Protocol Error: Unexpected protocol code: CSQLSTATE58000且不再发送预期的ReadyForQuery连接就此卡死Cloudflare 运行时在 30 秒处杀掉请求报错 error 1101该问题影响每一条读路径SQL DSL、ORM.all()/.first()、for awaitcursor 决策是在驱动层对每次读取做的没有单调用短路开关把读取包进withTransaction(...)不能规避——故障点在 Hyperdrive 的协议解析状态不在连接绑定驱动 catch 块里回退 simple-query 模式的保护也不生效因为回退只在特定抛错时触发而挂起本身不抛错。如果你的现象是任意读都挂、本地复现不了、30 秒被 1101 杀掉基本可以判定命中该缺陷。反过来只有某一条查询慢、或写路径异常则不属于这个根因应先看下面区分一节的其他已知问题。确认触发条件Hyperdrive 前置 cursor 默认开启两个条件同时满足才会触发。对照你的 Worker 代码检查连接串走 Hyperdrive。每请求 runtime 的取法是把env.HYPERDRIVE.connectionString传给db.connect({ url })例如 examples/prisma-8-cloudflare-worker/src/worker.tsawait using runtime await db.connect({ url: env.HYPERDRIVE.connectionString });postgresServerless未显式关闭 cursor。该门面与长驻postgres()门面的默认值相反postgresServerless默认cursor 开启面向流式读取 提前返回的每请求形态而长驻门面默认cursor: { disabled: true }。参考实现 examples/prisma-8-cloudflare-worker/src/prisma/db.ts 中未传cursor选项即默认开启状态import postgresServerless from prisma/orm-postgres/serverless; export const db postgresServerlessContract({ contractJson, middleware: createMiddleware(), // 未传 cursor —— 默认 enabledorigin 在 Hyperdrive 后时必须改为 disabled });注意部署指南原文写作internal/postgres/serverless示例工程实际 import 的是prisma/orm-postgres/serverless二者指同一门面以示例工程为准。为什么本地集成测试测不出来这是排查中最容易误导的一点文档明确说明M1 审计用 miniflare 模拟器与 localhost Postgres 验证过pgpg-cursor的完整路径open / read / cursor early-break / close均不复现挂起缺陷只在真实部署的 Hyperdrive 配置下出现。因此示例工程的vitest-pool-workers集成测试test/worker.integration.test.ts把 Hyperdrive binding 指向本地 Docker Postgrescursor 开启时也能全绿——本地测试通过不构成线上可用的证明该缺陷被文档标注为正在上游跟踪的 Cloudflare Hyperdrive bug在上游修复落地前对真实 Hyperdrive 必须保持 cursor 关闭。另有一个容易混淆的本地挂起属于独立问题早期尝试用prisma devPGlite 经 TCP 暴露的 Postgres作为本地 origin 时wrangler dev下每个碰库路由都会在 miniflare 的 Hyperdrive 模拟器中卡住pg-cloudflaresocket 报 Connection terminated unexpectedly。文档判断其与 PGlite TCP shim 和pg-cloudflaresocket 层在 workerd 中的交互有关。遇到本地挂起先确认你用的是不是 Docker Postgres示例工程为postgres:16跑在 5433 端口而不是把本地 PGlite 问题当成线上 Hyperdrive 缺陷处理。修复关闭 cursor 路径在模块作用域的db构造处src/prisma/db.ts这类文件传入cursor: { disabled: true }强制走 simple-protocol 路径export const db postgresServerlessContract({ contractJson, middleware: createMiddleware(), cursor: { disabled: true }, // REQUIRED if your origin is behind Cloudflare Hyperdrive });文档的措辞是非 Hyperdrive 的 origin 上保持默认即可无需改动。如果你的 Worker 只服务 Hyperdrive 前置的库直接把该选项写死在模块里即可它是门面级选项对每次connect()创建的 runtime 生效。部署侧没有额外动作wrangler.jsonc中 Hyperdrive binding 的id由pnpm exec wrangler hyperdrive create my-hyperdrive --connection-stringpostgres://USER:PASSHOST:PORT/DBNAME打印后替换示例仓库提交的是00000000…占位 id不替换则部署会失败。本地开发用的连接串放在.env的WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE中而不是.dev.vars——后者是运行时 Worker 密钥WRANGLER_*变量由 Wrangler 自身在构建本地 Hyperdrive binding 时消费新 Wrangler 中该前缀正被CLOUDFLARE_*取代wrangler4.87时两者均可用。验证本地测试套件与重新部署仓库给出的pattern 是否端到端可用的规范参考是示例工程自带的vitest-pool-workers集成测试它在workerd下启动 Worker把 Hyperdrive binding 指向本地 Docker Postgres覆盖 SQL DSL、ORM、事务和 cursor early-break。在examples/prisma-8-cloudflare-worker/下按文档顺序执行pnpm db:up # docker compose up -d --waitpostgres:16 on :5433 pnpm db:init # prisma db init → CREATE TABLE … pnpm seed # 插入 Alice Bob 50 posts pnpm test # vitest run --config vitest.config.ts本地手工冒烟pnpm dev起wrangler dev后curl http://localhost:8787/health curl http://localhost:8787/orm/users?limit5真正的回归确认发生在真实 Hyperdrive 上修改后pnpm run deploy重新部署注意用pnpm run deploy直接pnpm deploy会与 pnpm 内置命令冲突并报ERR_PNPM_INVALID_DEPLOY_TARGET然后观察此前挂起的读路由是否恢复正常返回而不是 30 秒后被 error 1101 杀掉。上游 Hyperdrive 修复落地前不要重新开启 cursor。区分其他挂起与连接类错误以下问题在文档中单独立项不要和 Hyperdrive cursor 缺陷混判wrangler dev能起但/orm/users返回 500 / connection error——本地容器多半停了或忘了pnpm db:up用docker compose ps确认容器健康pnpm db:reset可从干净状态恢复。注意db:down/db:reset会docker compose down -v丢弃容器和数据卷示例中数据为tmpfs承载执行前确认可以丢本地数据。pnpm db:up报Cannot connect to the Docker daemon——容器运行时没起启动 Docker Desktop / OrbStack 等后重试。pnpm db:init连接错误——确认db:up成功且端口是 5433 而非 5432与prisma-8-demo的 Postgres.app 撞端口会在此暴露。事务边界问题——withTransaction(runtime, ...)体内所有语句都在该 per-request runtime 的单条pg.Client上执行在事务体内另开第二个await using runtime2 await db.connect(...)并把部分语句路由过去行为未定义。大结果集内存——isolate 默认 128 MiBWorkers Unbound 更高ORMfindMany形态会把结果集物化进 JS 数组limit(...)是硬上限需要流式时用 SQL DSL 的runtime.execute(...)/runtime.query(...)迭代器加for await ... break。迁移不走 Hyperdrive——prisma db migrate等控制面命令必须从 Node 直连 origin 库连接串执行不要经过 Hyperdrive其边缘查询结果缓存会导致迁移台账脏读这是部署管线问题与运行期挂起无关。上游 Hyperdrive 的修复落地后可以移除cursor: { disabled: true }恢复默认流式路径并用上面的集成测试套件重新回归。【免费下载链接】ormNext-generation ORM for Node.js TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB项目地址: https://gitcode.com/GitHub_Trending/pr/orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Prisma Next postgresServerless 在 Cloudflare Hyperdrive 后查询挂起怎么排查【免费下载链接】ormNext-generation ORM for Node.js TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB项目地址: https://gitcode.com/GitHub_Trending/pr/orm如果你的 Cloudflare Worker 使用 Prisma Next 的postgresServerless每请求门面访问 Hyperdrive 前置的 Postgres线上读查询长时间无响应、最终请求被 Cloudflare 运行时在 30 秒处杀掉并返回 error 1101而本地wrangler dev和集成测试却一切正常——这就是本文要排查的场景。仓库文档已将该现象定位为 Hyperdrive 侧的协议解析问题并给出了明确的工作方案在postgresServerless({...})传入cursor: { disabled: true }。适用前提部署形态是 Cloudflare Workers Hyperdrive连接串来自env.HYPERDRIVE.connectionString完整示例在 examples/prisma-8-cloudflare-worker。症状判定是否命中 Hyperdrive 的挂起缺陷Serverless Deployment Guide 的 Known limitations 一节的实测结论2026 年 5 月生产 smoke 验证是默认 cursor 路径在真实 Hyperdrive 下会挂起具体表现为——pg-cursor的扩展查询命名 portal 协议中客户端在返回行后发送Close portal SyncHyperdrive 回复Protocol Error: Unexpected protocol code: CSQLSTATE58000且不再发送预期的ReadyForQuery连接就此卡死Cloudflare 运行时在 30 秒处杀掉请求报错 error 1101该问题影响每一条读路径SQL DSL、ORM.all()/.first()、for awaitcursor 决策是在驱动层对每次读取做的没有单调用短路开关把读取包进withTransaction(...)不能规避——故障点在 Hyperdrive 的协议解析状态不在连接绑定驱动 catch 块里回退 simple-query 模式的保护也不生效因为回退只在特定抛错时触发而挂起本身不抛错。如果你的现象是任意读都挂、本地复现不了、30 秒被 1101 杀掉基本可以判定命中该缺陷。反过来只有某一条查询慢、或写路径异常则不属于这个根因应先看下面区分一节的其他已知问题。确认触发条件Hyperdrive 前置 cursor 默认开启两个条件同时满足才会触发。对照你的 Worker 代码检查连接串走 Hyperdrive。每请求 runtime 的取法是把env.HYPERDRIVE.connectionString传给db.connect({ url })例如 examples/prisma-8-cloudflare-worker/src/worker.tsawait using runtime await db.connect({ url: env.HYPERDRIVE.connectionString });postgresServerless未显式关闭 cursor。该门面与长驻postgres()门面的默认值相反postgresServerless默认cursor 开启面向流式读取 提前返回的每请求形态而长驻门面默认cursor: { disabled: true }。参考实现 examples/prisma-8-cloudflare-worker/src/prisma/db.ts 中未传cursor选项即默认开启状态import postgresServerless from prisma/orm-postgres/serverless; export const db postgresServerlessContract({ contractJson, middleware: createMiddleware(), // 未传 cursor —— 默认 enabledorigin 在 Hyperdrive 后时必须改为 disabled });注意部署指南原文写作internal/postgres/serverless示例工程实际 import 的是prisma/orm-postgres/serverless二者指同一门面以示例工程为准。为什么本地集成测试测不出来这是排查中最容易误导的一点文档明确说明M1 审计用 miniflare 模拟器与 localhost Postgres 验证过pgpg-cursor的完整路径open / read / cursor early-break / close均不复现挂起缺陷只在真实部署的 Hyperdrive 配置下出现。因此示例工程的vitest-pool-workers集成测试test/worker.integration.test.ts把 Hyperdrive binding 指向本地 Docker Postgrescursor 开启时也能全绿——本地测试通过不构成线上可用的证明该缺陷被文档标注为正在上游跟踪的 Cloudflare Hyperdrive bug在上游修复落地前对真实 Hyperdrive 必须保持 cursor 关闭。另有一个容易混淆的本地挂起属于独立问题早期尝试用prisma devPGlite 经 TCP 暴露的 Postgres作为本地 origin 时wrangler dev下每个碰库路由都会在 miniflare 的 Hyperdrive 模拟器中卡住pg-cloudflaresocket 报 Connection terminated unexpectedly。文档判断其与 PGlite TCP shim 和pg-cloudflaresocket 层在 workerd 中的交互有关。遇到本地挂起先确认你用的是不是 Docker Postgres示例工程为postgres:16跑在 5433 端口而不是把本地 PGlite 问题当成线上 Hyperdrive 缺陷处理。修复关闭 cursor 路径在模块作用域的db构造处src/prisma/db.ts这类文件传入cursor: { disabled: true }强制走 simple-protocol 路径export const db postgresServerlessContract({ contractJson, middleware: createMiddleware(), cursor: { disabled: true }, // REQUIRED if your origin is behind Cloudflare Hyperdrive });文档的措辞是非 Hyperdrive 的 origin 上保持默认即可无需改动。如果你的 Worker 只服务 Hyperdrive 前置的库直接把该选项写死在模块里即可它是门面级选项对每次connect()创建的 runtime 生效。部署侧没有额外动作wrangler.jsonc中 Hyperdrive binding 的id由pnpm exec wrangler hyperdrive create my-hyperdrive --connection-stringpostgres://USER:PASSHOST:PORT/DBNAME打印后替换示例仓库提交的是00000000…占位 id不替换则部署会失败。本地开发用的连接串放在.env的WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE中而不是.dev.vars——后者是运行时 Worker 密钥WRANGLER_*变量由 Wrangler 自身在构建本地 Hyperdrive binding 时消费新 Wrangler 中该前缀正被CLOUDFLARE_*取代wrangler4.87时两者均可用。验证本地测试套件与重新部署仓库给出的pattern 是否端到端可用的规范参考是示例工程自带的vitest-pool-workers集成测试它在workerd下启动 Worker把 Hyperdrive binding 指向本地 Docker Postgres覆盖 SQL DSL、ORM、事务和 cursor early-break。在examples/prisma-8-cloudflare-worker/下按文档顺序执行pnpm db:up # docker compose up -d --waitpostgres:16 on :5433 pnpm db:init # prisma db init → CREATE TABLE … pnpm seed # 插入 Alice Bob 50 posts pnpm test # vitest run --config vitest.config.ts本地手工冒烟pnpm dev起wrangler dev后curl http://localhost:8787/health curl http://localhost:8787/orm/users?limit5真正的回归确认发生在真实 Hyperdrive 上修改后pnpm run deploy重新部署注意用pnpm run deploy直接pnpm deploy会与 pnpm 内置命令冲突并报ERR_PNPM_INVALID_DEPLOY_TARGET然后观察此前挂起的读路由是否恢复正常返回而不是 30 秒后被 error 1101 杀掉。上游 Hyperdrive 修复落地前不要重新开启 cursor。区分其他挂起与连接类错误以下问题在文档中单独立项不要和 Hyperdrive cursor 缺陷混判wrangler dev能起但/orm/users返回 500 / connection error——本地容器多半停了或忘了pnpm db:up用docker compose ps确认容器健康pnpm db:reset可从干净状态恢复。注意db:down/db:reset会docker compose down -v丢弃容器和数据卷示例中数据为tmpfs承载执行前确认可以丢本地数据。pnpm db:up报Cannot connect to the Docker daemon——容器运行时没起启动 Docker Desktop / OrbStack 等后重试。pnpm db:init连接错误——确认db:up成功且端口是 5433 而非 5432与prisma-8-demo的 Postgres.app 撞端口会在此暴露。事务边界问题——withTransaction(runtime, ...)体内所有语句都在该 per-request runtime 的单条pg.Client上执行在事务体内另开第二个await using runtime2 await db.connect(...)并把部分语句路由过去行为未定义。大结果集内存——isolate 默认 128 MiBWorkers Unbound 更高ORMfindMany形态会把结果集物化进 JS 数组limit(...)是硬上限需要流式时用 SQL DSL 的runtime.execute(...)/runtime.query(...)迭代器加for await ... break。迁移不走 Hyperdrive——prisma db migrate等控制面命令必须从 Node 直连 origin 库连接串执行不要经过 Hyperdrive其边缘查询结果缓存会导致迁移台账脏读这是部署管线问题与运行期挂起无关。上游 Hyperdrive 的修复落地后可以移除cursor: { disabled: true }恢复默认流式路径并用上面的集成测试套件重新回归。【免费下载链接】ormNext-generation ORM for Node.js TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB项目地址: https://gitcode.com/GitHub_Trending/pr/orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
