用途
本技能面向需要在无服务器（Serverless）与边缘（Edge）环境中使用 Postgres 数据库的开发者，帮助在 Cloudflare Workers、Vercel Edge、Node.js 等运行时中搭建 Neon 或 Vercel Postgres。两者共用同一 Neon 后端：Neon 直连提供多云灵活性与分支 API，Vercel Postgres 在 Vercel 上零配置并自动注入环境变量。两者均基于 HTTP（无需 TCP），适合无服务器/边缘环境。
主要能力
- 连接池：使用带
-pooler.的连接串自动复用连接，避免无服务器环境连接耗尽。 - 类 Git 分支：Neon 支持数据库分支，可用于隔离开发与迁移历史。
- ORM 集成：推荐 Drizzle ORM（边缘兼容），也支持 Prisma（仅 Node.js 运行时）。
- 事务：Neon 提供数组式与回调式事务 API；Vercel Postgres 需手动 BEGIN/COMMIT/ROLLBACK。
- 迁移：支持原生 SQL、Drizzle Kit、Prisma Migrate 三种方式。
- 已知问题预防：文档列出 19 个常见问题及规避方法。
使用方式
- 安装依赖：Neon 直连用
npm install @neondatabase/serverless；Vercel Postgres 用npm install @vercel/postgres；配合 Drizzle 用npm install drizzle-orm@0.45.1 @neondatabase/serverless@1.0.2与npm install -D drizzle-kit@0.31.8。 - 获取连接串：在 https://neon.tech 创建项目，或运行
vercel postgres create与vercel env pull .env.local，也可用neonctl（neonctl@2.19.0）创建。必须使用带-pooler.的连接串并包含?sslmode=require。 - 配置环境变量：Neon 直连用
DATABASE_URL；Vercel 自动生成POSTGRES_URL（查询用）、POSTGRES_PRISMA_URL（Prisma 迁移用）、POSTGRES_URL_NON_POOLING（无服务器中避免使用）等。Cloudflare Workers 在wrangler.jsonc的vars中配置。 - 查询：必须使用模板标签语法
sql\...`` 以防 SQL 注入，禁止字符串拼接。 - 建表与迁移：可用原生 SQL、Drizzle（
npx drizzle-kit generate/migrate）或 Prisma（npx prisma migrate dev）。 - 部署测试：Cloudflare Workers 用
npx wrangler deploy，Vercel 用vercel deploy --prod，并用 curl 测试接口。
适用场景
- Cloudflare Workers、Vercel Edge 等边缘运行时访问 Postgres。
- 高并发无服务器函数需要连接池。
- 需要数据库分支进行开发隔离。
- 使用 Drizzle ORM 构建边缘兼容的数据层。
限制与关键规则
- 无服务器环境必须使用池化连接串，否则出现连接池耗尽。
- 连接串必须含
?sslmode=require。 - 边缘运行时不支持 TCP，须用
@neondatabase/serverless而非pg或postgres.js。 - Prisma 无法在 Cloudflare Workers 运行，需改用 Drizzle。
- 迁移须在 Node.js 环境执行，不能在边缘函数中运行。
- Vercel Postgres 手动事务须在 finally 中调用
client.release()，防止连接泄漏。 - 边缘函数事务应保持简短（<5s），避免超时。
- Neon 免费层约 5 分钟无活动后自动挂起，首次请求可能有 1-2 秒唤醒延迟；可将查询超时设为 >=10s，或设置最小计算单元 >0 关闭自动挂起。
- 免费层并发连接上限为 100。
文档还列出连接池耗尽、TCP 不支持、SQL 注入、缺少 SSL、连接泄漏、环境变量错误、事务超时、Prisma 兼容性、分支 API 鉴权、分支删除后连接串失效、冷启动超时、Drizzle 类型不匹配、跨分支迁移冲突、PITR 时间戳越界等问题及预防方法。