neon-postgres

Neon Serverless Postgres

适用场景

当你需要了解使用 Neon Serverless Postgres 的指南和最佳实践时，请使用此技能。涵盖设置、连接方式、分支、自动扩缩、缩容至零、只读副本、连接池、Neon Auth，以及 Neon CLI、MCP 服务、REST API、TypeScript SDK 和 Python SDK。适用于具体的 Neon 数据库或工具问题。

引导用户完成任何与 Neon 相关的任务：设置、连接、分支和高级功能。提供可用的 Neon 连接、已完成的功能配置，或来自 Neon 官方文档的具体答案。

Neon 是一个无服务器 Postgres 平台，通过分离计算和存储来提供自动扩缩、分支、即时恢复和缩容至零功能。它完全兼容 Postgres，可与支持 Postgres 的任何语言、框架或 ORM 配合使用。

Neon 文档

Neon 文档是所有 Neon 相关信息的权威来源。回复前务必根据官方文档核实相关说法。Neon 的功能和 API 会不断演进，因此应优先获取最新文档，而不是依赖训练数据。

获取 Markdown 格式的文档

任何 Neon 文档页面都可以通过以下两种方式获取 Markdown 格式的内容：

1. 在 URL 后添加 .md（最简单）：https://neon.com/docs/introduction/branching.md
2. 在标准 URL 上请求 text/markdown：curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching

两种方式返回相同的 Markdown 内容。使用你的工具支持的方式即可。

查找合适的页面

文档索引列出了所有可用页面及其 URL 和简短说明：

https://neon.com/docs/llms.txt

常见文档 URL 按下方主题链接分类。如果需要的页面未列出，请搜索文档索引：https://neon.com/docs/llms.txt。不要猜测 URL。

什么是 Neon

在提供实现建议之前，使用此页面了解架构说明和术语（组织、项目、分支、端点）。

链接：https://neon.com/docs/introduction/architecture-overview.md

入门

在引导用户首次设置 Neon 时使用此部分。

检查现状

开始设置之前，检查用户的代码库和环境：

• 现有的数据库连接代码
• 现有的 Neon MCP 服务或 Neon CLI 配置
• 是否存在 .env 文件和 DATABASE_URL 环境变量
• 现有的 ORM（Prisma、Drizzle、TypeORM）配置

使用 Neon CLI 或 MCP 服务自主设置

提供帮助，使用 Neon CLI 或 MCP 服务检查现有的已连接 Neon 项目，或创建新项目。如果两者都尚未设置，请先说明安装、创建 API 密钥和主机配置变更，并取得用户对该范围操作的授权。使用 --agent 标志前，请查看固定版本的 CLI 发布说明及当前帮助信息。身份验证会自动处理。如果用户尚未登录，系统会打开浏览器进行 OAuth，并等待完成后再继续。

npx -y neon@latest init --agent <agent-name>

支持的 --agent 值：cursor、copilot、claude、claude-desktop、codex、opencode、cline、gemini-cli、goose、zed。

此操作会安装 Neon 扩展（适用于 Cursor/VS Code）或 MCP 服务（适用于其他 Agent），创建 API 密钥，并将 neon-postgres Agent 技能添加到项目中。

如果 init 不适用，可以通过非交互方式单独执行各个步骤：

• 扩展： cursor --install-extension databricks.neon-local-connect
• MCP 服务： npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>
• Agent 技能： npx skills add neondatabase/agent-skills --skill neon-postgres --agent <agent-name> -y

完整的 CLI 安装选项请参阅 https://neon.com/docs/reference/cli-install.md

设置流程

1. 选择组织和项目

使用 MCP 服务或 CLI 列出组织和项目。让用户选择现有项目或创建新项目。

2. 获取连接字符串

使用 MCP 服务或 CLI 获取连接字符串。将其存储在私有且被 Git 忽略的 .env 文件中，作为 DATABASE_URL，同时保留已有键。检查键名时，不要将凭据值打印到聊天或日志中。部署时使用密钥管理器。

3. 选择连接方式和驱动程序

参考连接方式指南，根据部署平台选择正确的驱动程序：https://neon.com/docs/connect/choose-connection.md

4. 使用 Neon Auth 进行用户身份验证（如有需要）

对于 CLI 工具、脚本或没有用户账号的应用，可跳过此步骤。如果应用需要身份验证：使用 MCP 服务的 provision_neon_auth 工具，然后参阅身份验证概览（https://neon.com/docs/auth/overview.md）进行设置。如需将身份验证与数据库查询结合使用，请参阅 JavaScript SDK 参考（https://neon.com/docs/reference/javascript-sdk.md）。

5. ORM 设置（可选）

检查是否已有 ORM（Prisma、Drizzle、TypeORM）。如果没有，询问用户是否需要使用 ORM。Drizzle 集成请参阅 https://neon.com/docs/guides/drizzle.md。

6. 架构设置

• 检查是否已有迁移文件或 ORM 架构
• 如果没有：提议创建示例架构，或一起设计架构

恢复设置

如果要恢复设置，请检查已完成的配置（MCP 连接、包含 DATABASE_URL 的 .env、依赖项、架构），然后从下一个未完成的步骤继续。

安全提醒

提醒用户使用环境变量存储凭据，绝不要提交连接字符串，并使用遵循最小权限原则的数据库角色。

连接方式和驱动程序

在需要根据运行时限制（TCP、HTTP、WebSocket、边缘、无服务器、长时间运行）选择正确的传输方式和驱动程序时，请参考本节。

链接：https://neon.com/docs/connect/choose-connection.md

推荐：Drizzle + 适用于运行时的驱动程序

可以选择将 Neon 与 Drizzle 等 ORM 搭配使用，以便轻松管理架构和迁移。根据运行时处理代码的方式选择驱动程序：

• 长时间运行或共享运行时环境 → node-postgres（pg）。 Neon Functions，以及任何在多个请求间共享函数运行时／运行于弹性计算环境的主机（例如使用 Fluid compute 的 Vercel），都会让模块级进程在多个请求间保持运行。在模块作用域中仅创建一次 pg 连接池，并在多个请求间重复使用。
• 完全隔离的无服务器环境（Lambda 式）→ Neon 的无服务器驱动程序（@neondatabase/serverless）。 不要假设主机会在每次请求后销毁所有实例；请检查实际部署中的复用和并发情况。无服务器驱动程序通过 HTTP 执行查询，专为此类场景打造。

Neon Functions / Vercel / 弹性计算 — Drizzle + node-postgres：

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import * as schema from "./schema";

// Created once at module scope; reused by every request the instance handles.
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
const db = drizzle({ client: pool, schema });

在 Vercel（Fluid compute）上，还要使用 @vercel/functions 中的 attachDatabasePool 附加连接池，以便函数运行时在实例暂停前关闭空闲连接：

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { attachDatabasePool } from "@vercel/functions";
import * as schema from "./schema";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
attachDatabasePool(pool); // let the Vercel runtime manage the pooled connections
const db = drizzle({ client: pool, schema });

Netlify 和其他完全隔离的无服务器环境 — Drizzle + Neon 无服务器驱动程序：

import { drizzle } from "drizzle-orm/neon-http";
import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);
const db = drizzle({ client: sql });

无服务器驱动程序

适用于 @neondatabase/serverless 模式，包括 HTTP 查询、WebSocket 事务和特定运行时的优化。

链接：https://neon.com/docs/serverless/serverless-driver.md

Neon JS SDK

适用于结合使用 Neon Auth 和 Data API 的工作流，包括 PostgREST 风格的查询和类型化客户端设置。

链接：https://neon.com/docs/reference/javascript-sdk.md

开发者工具

用于本地开发支持，使用 npx -y neon@latest init --agent <agent-name>，以及 VSCode 扩展设置和 Neon MCP 服务配置。

工具	URL
CLI 初始化命令	https://neon.com/docs/reference/cli-init.md
VSCode 扩展	https://neon.com/docs/local/vscode-extension.md
MCP 服务	https://neon.com/docs/ai/neon-mcp-server.md
Neon CLI	https://neon.com/docs/reference/neon-cli.md

Neon CLI

用于终端优先的工作流、脚本和 CI/CD 自动化，使用 neon。

链接：https://neon.com/docs/reference/neon-cli.md

Neon Admin API

Neon Admin API 可用于以编程方式管理 Neon 资源。Neon CLI 和 MCP 服务在后台使用它，但也可以直接用于更复杂的自动化工作流，或将 Neon 嵌入其他应用程序时使用。

Neon REST API

用于直接的 HTTP 自动化、端点级控制、API 密钥认证、速率限制处理和操作轮询。

链接：https://neon.com/docs/reference/api-reference.md

Neon TypeScript SDK

用于在 TypeScript 中通过 @neondatabase/api-client 实现对 Neon 资源的类型化编程控制。

链接：https://neon.com/docs/reference/typescript-sdk.md

Neon Python SDK

用于在 Python 中使用 neon-api 包实现编程式 Neon 管理。

链接：https://neon.com/docs/reference/python-sdk.md

Neon Auth

用于托管用户认证设置、UI 组件、认证方法，以及 Next.js 和 React 应用中 Neon Auth 集成的常见陷阱。

链接：https://neon.com/docs/auth/overview.md

Neon Auth 也内嵌在 Neon JS SDK 中。根据你的使用场景，你可能希望使用 Neon JS SDK 而非单独使用 Neon Auth。更多详情请参阅 https://neon.com/docs/connect/choose-connection.md。

Neon 基础设施即代码（neon.ts）

neon.ts 是 Neon 的分支配置和基础设施即代码文件：声明你的分支拥有哪些服务，获取类型安全的 env 变量，并以编程方式配置每个分支的计算资源——全部使用 TypeScript（完整参考请参阅 neon 技能）。Postgres 始终存在于每个分支上，因此你永远不需要声明数据库本身；你在此处编写代码化的是 Postgres 周边表面——Neon Auth、Data API 以及每个分支的计算设置（自动扩缩容和缩容至零）。

使用 @neon/config 添加它：

npm i @neon/config

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  auth: true, // Neon Auth (adds NEON_AUTH_* env vars)
  dataApi: true, // Data API (adds NEON_DATA_API_URL); requires auth: true (or an external IdP)
  // Postgres exists on every branch; tune its compute per branch:
  branch: (branch) => {
    if (branch.exists) return {}; // leave existing branches untouched
    if (branch.isDefault) return { protected: true }; // prod keeps default compute
    return {
      ttl: "7d", // non-prod branches auto-expire (max 30d)
      postgres: {
        computeSettings: {
          autoscalingLimitMinCu: 0.25, // active compute floor; suspension is configured separately
          autoscalingLimitMaxCu: 1, // keep dev/preview cheap
          suspendTimeout: "5m",
        },
      },
    };
  },
});

从 CLI 协调声明——相当于 Neon 的 terraform plan / apply：

neon config status   # print the branch's live config
neon config plan     # dry-run diff of what apply would change
neon config apply    # provision the declared services / settings
neon deploy          # alias for `neon config apply`

由于 neon checkout 在创建分支时会应用策略，新分支启动时这些计算设置（以及 Auth / Data API）已经就位。检出_现有_分支永远不会协调它——运行 neon deploy 来应用更改。

由于 neon.ts 是 TypeScript，无效的组合会编译失败并给出可操作的错误信息：Data API 默认通过 Neon Auth 验证请求，因此 dataApi: true 而没有 auth: true 是一个类型错误（修复方法——auth: true，或使用 authProvider: 'external' 并配合 jwksUrl——在错误信息中）。请参阅 neon 技能的类型安全配置说明。

使用 @neon/env 中的 parseEnv 读回生成的 env，它经过类型化并根据策略进行验证：

import { parseEnv } from "@neon/env";
import config from "./neon";

const env = parseEnv(config);
env.postgres.databaseUrl; // typed; enabling auth / dataApi above surfaces env.auth / env.dataApi

分支

当用户计划创建隔离环境、测试架构迁移、部署预览环境或自动化分支生命周期时，请使用此功能。

要点：

• 分支是即时的写时复制克隆（不会完整复制数据）。
• 分支可能附有关联的计算端点；请检查实际的分支和端点状态，不要假定每个分支都已有端点。
• 使用 neon CLI 或 MCP 服务创建、检查和比较分支。

链接：https://neon.com/docs/introduction/branching.md

如需了解详细的分支创建工作流（常规分支与仅架构分支、从父分支重置、CLI/MCP 选择），如果已安装，请使用 neon-postgres-branches 技能。

或者，从以下 URL 获取完整的分支技能：

https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md

如果尚未安装此技能，可以使用以下命令安装：

npx skills add neondatabase/agent-skills --skill neon-postgres-branches

自动扩缩

当用户需要计算资源根据工作负载自动扩缩，并希望了解 CU 规格和运行时行为时，请使用此功能。

链接：https://neon.com/docs/introduction/autoscaling.md

缩容至零

当用户希望优化闲置成本并讨论暂停/恢复行为（包括冷启动的权衡）时，请使用此功能。

要点：

• 闲置的计算资源会自动暂停（默认为 5 分钟，可配置）（除非已禁用——仅适用于 launch & scale 计划）
• 暂停后执行的首次查询通常会受到冷启动影响（约数百毫秒）
• 计算资源暂停期间，存储仍保持活动状态。

链接：https://neon.com/docs/introduction/scale-to-zero.md

即时恢复

当用户需要时间点恢复，或希望在不采用传统备份恢复工作流的情况下恢复数据状态时，请使用此功能。

要点：

• 即时恢复的历史记录窗口取决于计划限制。
• 用户可以从历史时间点创建分支。
• 可使用 Time Travel 查询进行历史检查。

链接：https://neon.com/docs/introduction/branch-restore.md

只读副本

对于读密集型工作负载，如果用户需要专用的只读计算资源且不想复制存储，请使用此功能。

要点：

• 副本是只读计算端点，共享同一存储。
• 创建速度快，扩缩独立于主计算资源。
• 典型用例：分析、报告和读密集型 API。

链接：https://neon.com/docs/introduction/read-replicas.md

连接池

当用户处于无服务器或高并发环境，并需要安全、可扩展的 Postgres 连接管理时，请使用此功能。

要点：

• Neon 连接池使用 PgBouncer。
• 在端点主机名中添加 -pooler，即可使用连接池连接。
• 对于并发突发的无服务器运行时，连接池尤为重要。

链接：https://neon.com/docs/connect/connection-pooling.md

IP 允许列表

当用户需要通过可信网络、IP 或 CIDR 范围限制数据库访问时，请使用此功能。

链接：https://neon.com/docs/introduction/ip-allow.md

逻辑复制

当用户需要集成 CDC 管道、外部 Postgres 同步或基于复制的数据迁移时，请使用此功能。

要点：

• Neon 支持原生逻辑复制工作流。
• 适用于与外部 Postgres 系统之间进行复制。

链接：https://neon.com/docs/guides/logical-replication-guide.md

限制

• 仅当任务明确属于其上游产品或 API 范围时，才使用此技能。
• 在进行更改前，请根据当前官方文档核实命令、API 行为、定价、配额、凭据和部署影响。
• 不要将生成的示例视为环境特定测试、安全审查或用户批准破坏性或高成本操作的替代品。

安装集成、创建分支或协调配置的命令会更改本地或远程状态，并可能产生费用。经授权执行应用操作前，先查看只读状态或计划；分支克隆可能包含生产环境中的个人数据，因此预览时优先使用仅含架构的数据或经过清理的样本。此捆绑包不含 CLI 实现或配套的 neon 技能。使用前，必须根据链接的最新文档核实产品 API、主机行为和示例；文档检索可能失败，且不得将其报告为已完成核实。