Communitygithub.com

agents-inc/skills

无服务器 PostgreSQL,支持分支、自动扩缩容和兼容边缘环境的驱动程序

skills 是什么?

此技能提供关于 Neon 的全面指南,Neon 是一个无服务器 PostgreSQL 平台,专为边缘计算和无服务器运行时设计。它详细介绍了如何使用 `@neondatabase/serverless` 驱动程序,该驱动通过 HTTP 和 WebSocket 替代传统的 TCP 连接,使 PostgreSQL 可在 Cloudflare Workers、Vercel Edge Functions 等环境中使用。该技能涵盖五种核心模式:使用 `neon()` 进行快速、无状态的 HTTP 查询;使用 `Pool`/`Client` 进行交互式 WebSocket 事务;配置连接字符串(通过 `-pooler` 后缀实现池化连接 vs 直接连接);处理冷启动(计算资源从零扩展时 200-500 毫秒的唤醒延迟);以及利用 Neon 的快照复制(copy-on-write)机制进行数据库分支,以创建开发、预览和 CI 环境。它强调在无服务器环境中必须正确管理连接生命周期(在同一个请求处理程序内创建和关闭池),并且鼓励主要使用池化连接,以实现最佳并发性能。该技能还涵盖了用于非交互式 HTTP 事务的 `sql.transaction()`、用于动态 SQL 的 `sql.query()` 以及用于受信任标识符的 `sql.unsafe()`,并包含了使用 `neonctl` CLI 和 Neon API 进行编程分支管理的示例。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-baas-neon

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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/Client WebSocket 连接
  • 池化(-pooler)与直接连接字符串以及各自的使用场景
  • 数据库分支(开发分支、PR 预览分支、仅模式分支)
  • 从零扩展行为、冷启动缓解和自动扩缩容
  • 用于非交互式 HTTP 事务的 sql.transaction()
  • 用于程序化分支管理的 Neon API 和 neonctl CLI

何时不使用:

  • 传统的长连接服务器(使用带有 TCP 的标准 pg 驱动程序)
  • 复杂的 ORM 特定模式(请使用您 ORM 的专属技能)
  • 一般的 PostgreSQL 查询语法(请使用 SQL/Postgres 技能)

详细资源:

  • 有关决策框架和快速查找表,请参阅 reference.md

驱动程序和查询:

  • examples/core.md —— 驱动程序设置、HTTP 查询、WebSocket 连接、事务

分支与操作:


理念

Neon 将 PostgreSQL 的存储和计算分离,实现了传统 Postgres 无法实现的无服务器特性:从零扩展、即时分支和自动扩缩容。@neondatabase/serverless 驱动程序用 HTTP 和 WebSocket 替代 TCP,使得 Postgres 可以在缺乏 TCP 支持的边缘运行时中使用。

核心原则:

  1. HTTP 用于速度,WebSocket 用于会话 —— neon() 函数使用 HTTP fetch(约 3 次往返)进行单次查询。当你需要会话或交互式事务时,Pool/Client 使用 WebSocket(约 8 次往返)。为工作选择合适的传输方式。
  2. 默认使用池化连接 —— 池化连接通过 PgBouncer(事务模式)路由,可处理多达 10,000 个并发客户端。直接连接受限于计算资源大小(100-4,000),仅应用于需要会话状态的迁移或功能。
  3. 分支成本低廉 —— 快照复制意味着对一个 500GB 数据库创建分支不会分配额外存储空间,直到数据发生分歧。可自由地为开发、预览、测试和 CI 创建分支。
  4. 从零扩展是默认行为 —— 计算资源在闲置 5 分钟后暂停。冷启动需要 200-500 毫秒。通过设置超时、重试和连接池来应对此情况。
  5. 内置 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 | Serializable
  • readOnly:布尔值(默认 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 / NOTIFY
  • WITH 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

为何良好: 仅在需要时支付所需资源,无需手动调整数据库大小,平稳处理流量突发


资源

  • 参考 guide —— 决策框架和快速查找表
  • 核心示例 —— 驱动程序设置、HTTP 查询、WebSocket 连接、事务
  • 分支示例 —— 开发分支、PR 预览、neonctl CLI、Neon API、CI/CD 工作流
  • Neon 文档 —— 官方 Neon 文档

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

相关技能