neon-vercel-postgres

Neon 与 Vercel Serverless Postgres

状态：已可用于生产环境 最近更新：2025-11-21 依赖项：无 最新版本：@neondatabase/[email protected]、@vercel/[email protected]、[email protected]、[email protected]

---

快速开始（5 分钟）

1. 选择平台

选项 A：Neon Direct（多云、Cloudflare Workers、任何无服务器环境）

bun add @neondatabase/serverless

选项 B：Vercel Postgres（仅限 Vercel，在 Vercel 上无需配置）

bun add @vercel/postgres

为什么这很重要：

• Neon Direct 提供多云灵活性，并支持访问分支 API
• Vercel Postgres 在 Vercel 上无需配置，并提供自动环境变量
• 两者都基于 HTTP（不使用 TCP），非常适合无服务器／边缘环境

2. 获取连接字符串

对于 Neon Direct：

# Sign up at https://neon.tech
# Create a project → Get connection string
# Format: postgresql://user:[email protected]/dbname?sslmode=require

对于 Vercel Postgres：

# In your Vercel project
vercel postgres create
vercel env pull .env.local  # Automatically creates POSTGRES_URL and other vars

重要：

• 无服务器环境请使用池化连接字符串（以 -pooler.region.aws.neon.tech 结尾）
• 在无服务器环境中，非池化连接很快就会耗尽
• 始终包含 ?sslmode=require 参数

3. 查询数据库

Neon Direct：

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

const sql = neon(process.env.DATABASE_URL!);

// Simple query
const users = await sql`SELECT * FROM users WHERE id = ${userId}`;

// Transactions
const result = await sql.transaction([
  sql`INSERT INTO users (name) VALUES (${name})`,
  sql`SELECT * FROM users WHERE name = ${name}`
]);

Vercel Postgres：

import { sql } from '@vercel/postgres';

// Simple query
const { rows } = await sql`SELECT * FROM users WHERE id = ${userId}`;

// Transactions
const client = await sql.connect();
try {
  await client.sql`BEGIN`;
  await client.sql`INSERT INTO users (name) VALUES (${name})`;
  await client.sql`COMMIT`;
} finally {
  client.release();
}

重要：

• 使用模板标签语法（sql`...`）自动防止 SQL 注入
• 切勿拼接字符串：sql('SELECT * FROM users WHERE id = ' + id) ❌

---

关键规则

始终遵循

✅ 在无服务器环境中使用池化连接字符串（主机名中包含 -pooler.）

✅ 查询使用模板标签语法（sql`SELECT * FROM users`），以防止 SQL 注入

✅ 在连接字符串中包含 sslmode=require

✅ 事务结束后释放连接（Vercel Postgres 手动事务）

✅ 使用 Drizzle ORM 作为兼容边缘环境的 TypeScript ORM（在 Cloudflare Workers 中不要使用 Prisma）

✅ 将连接字符串设为环境变量（切勿硬编码）

✅ 在预览环境和测试中使用 Neon 分支

✅ 在 Neon 控制面板中监控连接池使用情况

✅ 使用 try/catch 代码块处理错误，并在失败时回滚事务

✅ 在 INSERT/UPDATE 中使用 RETURNING 子句，通过一次查询获取创建或更新的数据

绝不执行

❌ 切勿在无服务器函数中使用非池化连接（会耗尽连接池）

❌ 切勿拼接 SQL 字符串（'SELECT * FROM users WHERE id = ' + id）——有 SQL 注入风险

❌ 切勿省略 sslmode=require——连接将失败或不安全

❌ 使用 Vercel Postgres 手动事务时，切勿忘记调用 client.release()——会导致连接泄漏

❌ 切勿在 Cloudflare Workers 中使用 Prisma——它需要 Node.js 运行时（请改用 Drizzle）

❌ 切勿硬编码连接字符串——请使用环境变量

❌ 切勿从边缘函数运行迁移——请使用 Node.js 环境或 Neon 控制台

❌ 切勿提交 .env 文件——请将其加入 .gitignore

❌ 切勿在无服务器函数中使用 POSTGRES_URL_NON_POOLING——这会抵消池化的作用

❌ 切勿超出连接数限制——监控使用情况，必要时升级套餐

---

最常见的 5 个错误（完整的 15 个错误请参阅 references/error-catalog.md）

错误 #1：连接池耗尽

错误：Error: connection pool exhausted 或 too many connections for role 解决方案：使用池化连接字符串（以 -pooler.region.aws.neon.tech 结尾），不要使用非池化连接字符串

错误 #2：不支持 TCP 连接

错误：Error: TCP connections are not supported in this environment 解决方案：使用基于 HTTP 的 @neondatabase/serverless，不要使用基于 TCP 的 pg 或 postgres.js

错误 #3：字符串拼接导致 SQL 注入

错误：SQL 注入攻击成功 解决方案：始终使用模板标签（sql`SELECT * FROM users WHERE id = ${id}`），切勿拼接字符串

错误 #4：缺少 SSL 模式

错误：Error: connection requires SSL 解决方案：始终在连接字符串后追加 ?sslmode=require

错误 #5：连接泄漏（Vercel Postgres）

错误：内存使用量逐渐增加
解决方案：手动执行事务后，务必在 finally 块中调用 client.release()

加载 references/error-catalog.md，查看全部 15 个错误的详细解决方案和故障排查指南。

---

常见用例

用例 1：使用 Neon 的 Cloudflare Worker

适用场景：在 Cloudflare Workers 上部署使用 Postgres 的无服务器 API
快速模式：

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

export default {
  async fetch(request: Request, env: Env) {
    const sql = neon(env.DATABASE_URL);
    const users = await sql`SELECT * FROM users`;
    return Response.json(users);
  }
};

加载：references/common-patterns.md → 模式 1

用例 2：Next.js Server Actions

适用场景：使用 Vercel Postgres 构建 Next.js 应用
快速模式：

'use server';
import { sql } from '@vercel/postgres';

export async function getUsers() {
  const { rows } = await sql`SELECT * FROM users`;
  return rows;
}

加载：references/common-patterns.md → 模式 2

用例 3：使用 Drizzle 实现类型安全查询

适用场景：需要完整的 TypeScript 类型安全和边缘兼容性
加载：references/common-patterns.md → 模式 3

用例 4：数据库事务

适用场景：多个操作必须全部成功或全部失败（例如转账）
加载：references/common-patterns.md → 模式 4

用例 5：使用分支的预览环境

适用场景：需要为每个拉取请求／预览部署创建隔离的数据库
加载：references/common-patterns.md → 模式 5

---

何时加载参考资料

在以下情况下加载 references/setup-guide.md：

• 用户需要完整的 7 步设置流程
• 用户询问 Drizzle ORM 或 Prisma 集成
• 用户需要环境变量或连接字符串方面的帮助
• 用户询问如何部署到 Cloudflare Workers 或 Vercel

在以下情况下加载 references/error-catalog.md：

• 遇到任何连接、查询或部署错误
• 用户报告“连接池耗尽”或超时错误
• 用户询问如何防止 SQL 注入
• 用户需要排查 Prisma 或 Drizzle 问题

在以下情况下加载 references/common-patterns.md：

• 用户需要代码示例或模板
• 用户需要实现事务、分页或搜索
• 用户询问 Server Actions、Cloudflare Workers 或 Drizzle 模式
• 用户想查看经过生产环境验证的模式

在以下情况下加载 references/advanced-topics.md：

• 用户询问 Neon 分支或数据库工作流
• 用户需要深入了解连接池
• 用户询问性能优化或查询调优
• 用户需要安全最佳实践（RLS、加密、审计日志）
• 用户询问备份或灾难恢复

---

配置文件参考

package.json（Neon 直连）

{
  "dependencies": {
    "@neondatabase/serverless": "^1.0.2"
  }
}

package.json（Vercel Postgres）

{
  "dependencies": {
    "@vercel/postgres": "^0.10.0"
  }
}

package.json（使用 Drizzle ORM）

{
  "dependencies": {
    "@neondatabase/serverless": "^1.0.2",
    "drizzle-orm": "^0.44.7"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.0"
  },
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio"
  }
}

drizzle.config.ts

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './db/schema.ts',
  out: './db/migrations',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!
  }
});

这些设置的作用：

• @neondatabase/serverless 兼容边缘运行时（基于 HTTP/WebSocket）
• @vercel/postgres 在 Vercel 上提供零配置支持
• drizzle-orm 可在所有运行时中使用（Cloudflare Workers、Vercel Edge、Node.js）
• drizzle-kit 用于处理迁移和生成架构

---

使用随附资源

模板（templates/）

drizzle-schema.ts - 包含用户、帖子和关系的完整 Drizzle 架构

// See templates/drizzle-schema.ts for full example

drizzle-queries.ts - 常见查询模式（SELECT、INSERT、UPDATE、DELETE、连接查询）

// See templates/drizzle-queries.ts for full example

drizzle-migrations-workflow.md - 完整的迁移工作流指南

// See templates/drizzle-migrations-workflow.md for full guide

neon-basic-queries.ts - 使用 Neon 的原始 SQL 查询模式

// See templates/neon-basic-queries.ts for full example

package.json - 完整的依赖配置

// See templates/package.json for full config

参考资料（references/）

• setup-guide.md - 完整的 7 步设置流程（从安装到部署）
• error-catalog.md - 全部 15 个错误的解决方案和故障排查指南
• common-patterns.md - 5 种以上的生产环境模式（Cloudflare Workers、Next.js、Drizzle、事务、分支）
• advanced-topics.md - 分支工作流、连接池、性能、安全

---

依赖

必需：

• @neondatabase/serverless@^1.0.2 - Neon 无服务器 Postgres 客户端（基于 HTTP/WebSocket）
• @vercel/postgres@^0.10.0 - Vercel Postgres 客户端（Neon 直连方案的替代选择，专用于 Vercel）

可选：

• drizzle-orm@^0.44.7 - TypeScript ORM（兼容边缘运行环境，推荐）
• drizzle-kit@^0.31.0 - Drizzle 架构迁移和内省工具
• @prisma/client@^6.10.0 - Prisma ORM（仅支持 Node.js，不兼容边缘运行环境）
• @prisma/adapter-neon@^6.10.0 - Neon 无服务器版的 Prisma 适配器
• neonctl@^2.16.1 - 用于数据库管理的 Neon CLI
• zod@^3.24.0 - 用于输入净化的架构验证工具

---

官方文档

• Neon 文档：https://neon.tech/docs
• Neon 无服务器包：https://github.com/neondatabase/serverless
• Vercel Postgres：https://vercel.com/docs/storage/vercel-postgres
• Vercel Storage（全部）：https://vercel.com/docs/storage
• Neon 分支指南：https://neon.tech/docs/guides/branching
• Neonctl CLI：https://neon.tech/docs/reference/cli
• Drizzle + Neon：https://orm.drizzle.team/docs/quick-postgresql/neon
• Prisma + Neon：https://www.prisma.io/docs/orm/overview/databases/neon
• Context7 库 ID：/github/neondatabase/serverless、/github/vercel/storage

---

软件包版本（已于 2025-10-29 验证）

{
  "dependencies": {
    "@neondatabase/serverless": "^1.0.2",
    "@vercel/postgres": "^0.10.0",
    "drizzle-orm": "^0.44.7"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.0",
    "neonctl": "^2.16.1"
  }
}

最新 Prisma（如有需要）：

{
  "dependencies": {
    "@prisma/client": "^6.10.0",
    "@prisma/adapter-neon": "^6.10.0"
  },
  "devDependencies": {
    "prisma": "^6.10.0"
  }
}

---

生产环境示例

此技能基于 Neon 和 Vercel Postgres 的生产部署：

• Cloudflare Workers：API 每日处理 50K+ 个请求，连接错误为 0
• Vercel Next.js 应用：电商网站月活跃用户达 100K+
• 构建时间：<5 分钟（初始设置），<30s（部署）
• 错误：0（已避免所有 15 个已知问题）
• 验证：✅ 连接池，✅ SQL 注入防护，✅ 事务处理，✅ 分支工作流

---

完整设置检查清单

使用此清单验证设置：

• 已安装软件包（@neondatabase/serverless 或 @vercel/postgres）
• 已创建 Neon 数据库（或已配置 Vercel Postgres）
• 已获取连接池连接字符串（以 -pooler. 结尾）
• 连接字符串包含 ?sslmode=require
• 已配置环境变量（DATABASE_URL 或 POSTGRES_URL）
• 已创建数据库架构（原始 SQL、Drizzle 或 Prisma）
• 查询使用模板标签语法（sql`...`）
• 事务使用适当的 try/catch 并释放连接
• 已验证连接池（使用连接池连接字符串）
• ORM 选择适合运行环境（边缘运行环境使用 Drizzle，Node.js 使用 Prisma）
• 已使用开发数据库在本地测试
• 已在生产/预览环境中部署并测试
• 已在 Neon 控制面板中设置连接监控

---

有疑问？遇到问题？

1. 查看 references/error-catalog.md，了解全部 15 个错误及其故障排查方法
2. 查看 references/setup-guide.md，了解完整的 7 步设置流程
3. 查看 references/common-patterns.md，获取经过生产环境验证的代码示例
4. 查看官方文档：https://neon.tech/docs
5. 确保在无服务器环境中使用连接池连接字符串
6. 确认连接字符串中包含 sslmode=require