neon-postgres

Neon Serverless Postgres

引导用户完成任何与 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 项目或创建新项目的选项。如果两者都未设置，请使用 --agent 标志运行 init。使用 npx -y 跳过包安装提示。身份验证会自动处理。如果用户未登录，它会打开浏览器进行 OAuth 并等待完成后再继续。

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

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

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

如果 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>
• 代理技能： 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 获取连接字符串。将其存储为 .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）。如果没有，询问用户是否需要。有关 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 与 ORM（如 Drizzle）配对，以便于模式管理和迁移。根据运行时如何处理您的代码选择驱动程序：

• 长时间运行或共享运行时环境 → node-postgres (pg)。 Neon Functions 以及任何函数运行时在请求之间共享/在流体计算上运行的主机（例如 Vercel 的 Fluid compute），会在模块范围内保持进程存活以处理多个请求。在模块范围内一次打开一个 pg 池，并在请求之间重用。
• 完全隔离的无服务器（Lambda 风格）→ Neon 的无服务器驱动程序（@neondatabase/serverless）。 像 Netlify 这样的主机为每个请求启动一个全新的隔离实例，因此无法重用持久的 TCP 池；无服务器驱动程序通过 HTTP 进行查询，专为此场景构建。

Neon Functions / Vercel / fluid compute — Drizzle + node-postgres：

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

// 在模块范围内创建一次；由实例处理的每个请求重用。
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); // 让 Vercel 运行时管理池化连接
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 neonctl@latest init --agent <agent-name>、VSCode 扩展设置和 Neon MCP 服务器配置实现本地开发。

工具	URL
CLI Init 命令	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 自动化，使用 neonctl。

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

Neon Admin API

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

Neon REST API

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

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

Neon TypeScript SDK

当需要通过 @neondatabase/api-client 在 TypeScript 中实现类型化的 Neon 资源编程控制时使用。

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

Neon Python SDK

当需要使用 neon-api 包在 Python 中实现 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 的分支配置和基础设施即代码文件：声明您的分支具有哪些服务，获取类型安全的环境变量，并为每个分支编程计算——全部在 TypeScript 中完成（有关完整参考，请参阅 neon 技能）。Postgres 始终存在于每个分支上，因此您无需声明数据库本身；您在此处编写的是 Postgres 周边的表面——Neon Auth、Data API 以及每个分支的计算设置（自动扩缩容和自动暂停）。

使用 @neondatabase/config 添加：

npm i @neondatabase/config

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

export default defineConfig({
  auth: true, // Neon Auth（添加 NEON_AUTH_* 环境变量）
  dataApi: true, // Data API（添加 NEON_DATA_API_URL）；需要 auth: true（或外部 IdP）
  // Postgres 存在于每个分支上；按分支调整其计算：
  branch: (branch) => {
    if (branch.exists) return {}; // 保持现有分支不变
    if (branch.isDefault) return { protected: true }; // 生产环境保持默认计算
    return {
      ttl: "7d", // 非生产分支自动过期（最长 30 天）
      postgres: {
        computeSettings: {
          autoscalingLimitMinCu: 0.25, // 自动暂停
          autoscalingLimitMaxCu: 1, // 保持开发/预览成本低廉
          suspendTimeout: "5m",
        },
      },
    };
  },
});

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

neonctl config status   # 打印分支的实时配置
neonctl config plan     # 预览 apply 会更改的内容
neonctl config apply    # 配置声明的服务/设置
neonctl deploy          # `neonctl config apply` 的别名

因为 neonctl checkout 在创建分支时应用策略，所以新分支会立即应用这些计算设置（以及 Auth / Data API）。检出_现有_分支不会重新协调——运行 neonctl deploy 来应用更改。

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

使用 @neondatabase/env 中的 parseEnv 读取结果环境变量，并根据策略进行类型化和验证：

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

const env = parseEnv(config);
env.postgres.databaseUrl; // 类型化；启用 auth / dataApi 会暴露 env.auth / env.dataApi

分支

当用户计划隔离环境、模式迁移测试、预览部署或分支生命周期自动化时使用。

关键点：

• 分支是即时、写时复制的克隆（无需完整数据复制）。
• 每个分支都有自己的计算端点。
• 使用 neonctl 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 分钟，可配置）（除非禁用——仅限启动和扩展计划）
• 暂停后的第一次查询通常有冷启动惩罚（约几百毫秒）
• 计算暂停时存储保持活动状态。

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

即时恢复

当用户需要时间点恢复或希望恢复数据状态而不使用传统备份恢复工作流时使用。

关键点：

• 即时恢复的历史窗口取决于计划限制。
• 用户可以从历史时间点创建分支。
• 时间旅行查询可用于历史检查工作流。

链接：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