Neon 无服务器 PostgreSQL 模式
快速指南: 在边缘/无服务器数据库访问中使用
@neondatabase/serverless。对于单次查询(更快、无状态),优先使用neon()HTTP 函数;对于交互式事务,使用Pool/Client。对于无服务器工作负载,使用池化连接字符串(带有-pooler后缀);仅在进行数据库迁移时使用直接连接。利用快照复制语义,为开发/预览环境分支您的数据库。始终处理由于从零扩展导致的冷启动(200-500 毫秒唤醒)。
<critical_requirements>
关键:使用此技能前必读
所有代码必须遵循 CLAUDE.md 中的项目约定(kebab-case 命名格式、具名导出、导入顺序、
import type、具名常量)
(您必须在边缘/无服务器运行时中使用 neon() HTTP 函数进行单次查询——对于一次性操作,它比 WebSocket 快 2-3 倍)
(您必须在无服务器环境中在同一个请求处理程序内关闭 Pool/Client 连接——WebSocket 连接不能存活超过单个请求的生命周期)
(对于无服务器工作负载,必须使用池化连接字符串(-pooler 后缀)——直接连接会耗尽有限的连接槽位)
(您必须使用适当的连接超时和重试逻辑来处理从零扩展的唤醒延迟(200-500 毫秒))
(您只能对受信任的、已知安全的字符串(如表名、列名)使用 sql.unsafe()——绝不能用于用户输入)
</critical_requirements>
自动检测: Neon, @neondatabase/serverless, neon(), neonConfig, neon serverless driver, neon database, neon branch, neonctl, neon connection pooling, neon scale-to-zero, neon autoscaling, neon postgres, ep-*-pooler
何时使用:
- 从边缘/无服务器函数查询 Postgres(边缘运行时、无服务器平台)
- 为不同工作负载设置连接字符串(池化 vs 直接)
- 为开发、预览或 CI 环境创建数据库分支
- 管理从零扩展行为和冷启动优化
- 在无服务器上下文中运行事务(HTTP 批处理或 WebSocket)
- 通过 Neon API 或 neonctl CLI 进行程序化分支管理
涵盖的关键模式:
- 使用 SQL 标签模板和可组合片段的
neon()HTTP 查询 - 具有正确生命周期管理的
Pool/ClientWebSocket 连接 - 池化(
-pooler)与直接连接字符串以及各自的使用场景 - 数据库分支(开发分支、PR 预览分支、仅模式分支)
- 从零扩展行为、冷启动缓解和自动扩缩容
- 用于非交互式 HTTP 事务的
sql.transaction() - 用于程序化分支管理的 Neon API 和 neonctl CLI
何时不使用:
- 传统的长连接服务器(使用带有 TCP 的标准
pg驱动程序) - 复杂的 ORM 特定模式(请使用您 ORM 的专属技能)
- 一般的 PostgreSQL 查询语法(请使用 SQL/Postgres 技能)
详细资源:
- 有关决策框架和快速查找表,请参阅 reference.md
驱动程序和查询:
- examples/core.md —— 驱动程序设置、HTTP 查询、WebSocket 连接、事务
分支与操作:
- examples/branching.md —— 开发分支、PR 预览、neonctl CLI、Neon API、CI/CD 工作流
理念
Neon 将 PostgreSQL 的存储和计算分离,实现了传统 Postgres 无法实现的无服务器特性:从零扩展、即时分支和自动扩缩容。@neondatabase/serverless 驱动程序用 HTTP 和 WebSocket 替代 TCP,使得 Postgres 可以在缺乏 TCP 支持的边缘运行时中使用。
核心原则:
- HTTP 用于速度,WebSocket 用于会话 ——
neon()函数使用 HTTP fetch(约 3 次往返)进行单次查询。当你需要会话或交互式事务时,Pool/Client使用 WebSocket(约 8 次往返)。为工作选择合适的传输方式。 - 默认使用池化连接 —— 池化连接通过 PgBouncer(事务模式)路由,可处理多达 10,000 个并发客户端。直接连接受限于计算资源大小(100-4,000),仅应用于需要会话状态的迁移或功能。
- 分支成本低廉 —— 快照复制意味着对一个 500GB 数据库创建分支不会分配额外存储空间,直到数据发生分歧。可自由地为开发、预览、测试和 CI 创建分支。
- 从零扩展是默认行为 —— 计算资源在闲置 5 分钟后暂停。冷启动需要 200-500 毫秒。通过设置超时、重试和连接池来应对此情况。
- 内置 SQL 注入防护 —— 标签模板函数自动参数化输入。从 v1.0 开始,将
neon()作为普通函数调用会引发类型错误,从而防止意外注入。
何时使用 Neon 无服务器驱动程序:
- 无法打开 TCP 连接的边缘/无服务器函数
- 受益于数据库分支的应用程序(每个 PR 的预览环境)
- 受益于从零扩展的成本敏感型工作负载
- 需要连接池的高并发无服务器应用
何时不使用:
- 具有持久连接的长运行服务器进程(请通过 TCP 使用标准
pg) - 需要通过 PgBouncer 使用会话级功能的工作负载(LISTEN/NOTIFY、SET、临时表)
- 大于 16 CU 且需要始终在线的数据库(超过 16 CU 时不支持从零扩展)
核心模式
模式 1:使用 neon() 进行 HTTP 查询
neon() 函数使用 SQL 标签模板创建一个基于 HTTP 的查询函数。这是单次、非交互式查询的最快路径。
import { neon } from "@neondatabase/serverless";
const DATABASE_URL = process.env.DATABASE_URL!;
const sql = neon(DATABASE_URL);
// 标签模板 —— 参数自动参数化(防止注入)
const userId = "abc-123";
const posts =
await sql`SELECT id, title FROM posts WHERE author_id = ${userId}`;
为何良好: 标签模板自动参数化值以防止 SQL 注入,HTTP 约 3 次往返 vs WebSocket 约 8 次,无状态(无需管理连接)
// 错误:将 neon() 作为普通函数调用(v1.0+ 类型错误)
const sql = neon(DATABASE_URL);
const result = await sql(`SELECT * FROM posts WHERE id = ${id}`); // 类型错误 + SQL 注入风险
为何错误: 从 v1.0 开始,将查询函数作为普通函数(而非标签模板)调用会在运行时和类型上引发错误——此更改正是为了防止字符串插值导致的 SQL 注入
用于动态 SQL 的 sql.query()
当查询字符串在变量中(非模板字面量)时,使用带有编号占位符的 .query() 方法:
const q = "SELECT * FROM posts WHERE id = $1 AND status = $2";
const posts = await sql.query(q, [postId, "published"]);
何时使用: 运行时构建的动态 SQL 字符串,或存储在变量中的查询。参数仍通过 $1、$2 等进行安全参数化。
模式 2:可组合查询片段
模板查询支持组合,并且跨片段自动编号参数。
import { neon } from "@neondatabase/serverless";
const sql = neon(DATABASE_URL);
// 从可重用片段构建查询
const whereClause = sql`WHERE status = ${'active'} AND role = ${'admin'}`;
const orderClause = sql`ORDER BY created_at DESC`;
const PAGE_SIZE = 20;
const limitClause = sql`LIMIT ${PAGE_SIZE}`;
const users =
await sql`SELECT id, name, email FROM users ${whereClause} ${orderClause} ${limitClause}`;
为何良好: 参数在组合的片段间自动重新编号,页面大小使用命名常量,片段可在多个查询中重用
使用 sql.unsafe() 处理动态表/列名
// 仅用于受信任的、已知安全的值 —— 绝不能用于用户输入
const TABLE_NAME = "posts";
const results =
await sql`SELECT * FROM ${sql.unsafe(TABLE_NAME)} WHERE id = ${postId}`;
何时使用: 仅当需要插入无法在 SQL 中参数化的受信任标识符(表名、列名)时。切勿将用户提供的值传递给 sql.unsafe()。
模式 3:使用 sql.transaction() 进行 HTTP 事务
通过 HTTP 原子执行多个查询,无需 WebSocket 连接。
import { neon } from "@neondatabase/serverless";
const sql = neon(DATABASE_URL);
// 数组形式 —— 所有查询在单个 HTTP 往返中执行
const [posts, totalCount] = await sql.transaction([
sql`SELECT id, title FROM posts ORDER BY created_at DESC LIMIT 10`,
sql`SELECT count(*) FROM posts`,
]);
// 带事务选项的函数形式
const [, transferResult] = await sql.transaction(
(txn) => [
txn`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`,
txn`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`,
],
{ isolationLevel: "Serializable" },
);
为何良好: 无 WebSocket 开销的原子执行,数组形式对于只读批处理简洁明了,函数形式支持事务选项,隔离级别控制一致性保证
// 错误:将相关查询作为单独的 HTTP 请求运行
const posts = await sql`SELECT * FROM posts WHERE author_id = ${authorId}`;
const author = await sql`SELECT * FROM users WHERE id = ${authorId}`;
// 两次单独的 HTTP 往返,非原子操作,可能存在竞态条件
为何错误: 单独的 HTTP 调用不是原子的,数据可能在查询间发生变化,网络延迟加倍
事务选项
isolationLevel:ReadUncommitted|ReadCommitted|RepeatableRead|SerializablereadOnly:布尔值(默认false)deferrable:布尔值(默认false,仅当同时设置readOnly: true和Serializable时生效)
模式 4:使用 Pool/Client 的 WebSocket 连接
使用 Pool 和 Client 进行交互式事务,或实现与 node-postgres API 的兼容性。在无服务器环境中,必须在单个请求处理程序内创建和关闭连接。
import { Pool } from "@neondatabase/serverless";
export async function handleRequest(request: Request): Promise<Response> {
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
try {
// ... 查询 ...
} finally {
await pool.end(); // 始终在同一个请求内关闭
}
}
关键规则: 在处理程序内部创建 Pool,并在 finally 中使用 pool.end() 关闭。全局的 Pool 会在无服务器调用之间泄漏 WebSocket 连接。
请参阅 examples/core.md —— 模式 5-7,了解请求范围的池、交互式事务和 Node.js WebSocket 配置。
模式 5:连接字符串设置
Neon 提供两种连接字符串格式:池化(通过 PgBouncer)和直接。
# 池化连接(注意:端点 ID 上的 -pooler 后缀)
# 用于:无服务器函数、Web 应用、高并发工作负载
DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require
# 直接连接(无 -pooler 后缀)
# 用于:数据库迁移、pg_dump、LISTEN/NOTIFY、会话级功能
DIRECT_DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require
为何良好: 池化连接通过 PgBouncer 的事务模式处理最多 10,000 个并发客户端,直接连接为管理任务提供完整的会话功能,使用独立的环境变量使区别更加明确
PgBouncer 事务模式限制
池化连接以事务模式运行 PgBouncer,这意味着每个事务后连接会返回池中。这会禁止以下操作:
SET/RESET语句(请改用ALTER ROLE ... SET)LISTEN/NOTIFYWITH HOLD CURSOR- SQL 级别的
PREPARE/DEALLOCATE(支持最多 1,000 个协议级别的预编译语句) - 带有
PRESERVE/DELETE ROWS的临时表 - 会话级咨询锁
模式 6:冷启动和从零扩展处理
Neon 计算资源在无活动 5 分钟后自动暂停(默认)。冷启动需要 200-500 毫秒。通过适当的超时和重试逻辑来为此进行设计。
const CONNECTION_TIMEOUT_MS = 10_000;
const sql = neon(process.env.DATABASE_URL!, {
fetchOptions: { signal: AbortSignal.timeout(CONNECTION_TIMEOUT_MS) },
});
关键规则: 设置明确的超时时间(10-15 秒)以适应冷启动延迟。使用指数退避重试以提高可靠性。
请参阅 examples/core.md —— 模式 8,了解完整的超时配置和重试模式。
从零扩展事实
- 默认自动暂停:5 分钟无活动
- 冷启动延迟:约 200-500 毫秒(因区域和计算资源大小而异)
- 仅适用于最大 16 CU 的计算资源(更大的计算资源保持始终在线)
- 付费计划可以调整暂停超时时间(最多 7 天)或完全禁用
- 活动的逻辑复制订阅者会阻止暂停
模式 7:数据库分支
Neon 分支使用快照复制语义——对一个 500GB 数据库创建分支是瞬间完成的,并且在数据发生分歧之前不会分配额外存储空间。
# 安装 neonctl
npm install -g neonctl
# 从 main 创建一个开发分支
neonctl branches create --name dev-alice --project-id <project-id>
# 创建一个带有自动过期时间的分支(用于 CI/预览)
neonctl branches create --name preview/pr-42 --project-id <project-id> --expires-at "2025-04-01T00:00:00Z"
# 创建仅模式分支(不复制数据——用于敏感环境)
neonctl branches create --name ci-test --schema-only --project-id <project-id>
# 重置开发分支以匹配当前生产环境
neonctl branches reset dev-alice --parent --project-id <project-id>
# 删除一个分支
neonctl branches delete preview/pr-42 --project-id <project-id>
为何良好: 命名分支与 git 工作流对应,TTL 过期自动清理 CI 分支,仅模式分支保护敏感数据,重置操作无需重建即可同步开发环境与生产环境
分支与 Neon API
除了 neonctl,您还可以直接使用 Neon API 进行程序化分支管理:
const NEON_API_KEY = process.env.NEON_API_KEY;
const PROJECT_ID = process.env.NEON_PROJECT_ID;
// 列出分支
const response = await fetch(
`https://console.neon.tech/api/v2/projects/${PROJECT_ID}/branches`,
{
headers: {
Authorization: `Bearer ${NEON_API_KEY}`,
"Content-Type": "application/json",
},
},
);
const branches = await response.json();
模式 8:自动扩缩容
Neon 可以根据工作负载自动扩展计算资源。这允许计算资源在需求高时扩展,并在需求低时收缩至零。
# 在 neon.toml 或项目中配置
# 如果使用默认设置,自动扩缩容会自动启用,但您可以通过 API 调整最小和最大 CU
为何良好: 仅在需要时支付所需资源,无需手动调整数据库大小,平稳处理流量突发