neon-postgres

Neon Serverless Postgres

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 按主题整理在下方链接中。如果需要的页面未列出，请搜索文档索引，不要猜测 URL。

什么是 Neon

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

链接：references/what-is-neon.md

入门

首次设置时，请使用此文档：选择组织和项目、获取连接字符串、安装驱动、配置可选身份验证，以及初始架构设置。

链接：references/getting-started.md

连接方式和驱动

需要根据运行时限制（TCP、HTTP、WebSocket、边缘环境、无服务器、长时间运行）选择合适的传输方式和驱动时，请使用此文档。

链接：references/connection-methods.md

Serverless 驱动

了解 @neondatabase/serverless 的使用模式时，请使用此文档，包括 HTTP 查询、WebSocket 事务和特定运行时的优化。

链接：references/neon-serverless.md

Neon JS SDK

使用 PostgREST 风格的查询和类型化客户端设置，实现 Neon Auth + Data API 组合工作流时，请使用此文档。

链接：references/neon-js.md

开发者工具

在本地开发中使用 npx neonctl@latest init、设置 VSCode 扩展和配置 Neon MCP 服务时，请使用此文档。

链接：references/devtools.md

Neon CLI

使用 neonctl 进行以终端为主的工作流、编写脚本和实现 CI/CD 自动化时，请使用此文档。

链接：references/neon-cli.md

Neon Admin API

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

Neon REST API

进行直接 HTTP 自动化、端点级控制、API 密钥身份验证、速率限制处理和操作轮询时，请使用此文档。

链接：references/neon-rest-api.md

Neon TypeScript SDK

使用 @neondatabase/api-client 在 TypeScript 中实现对 Neon 资源的类型化编程控制时，请使用此文档。

链接：references/neon-typescript-sdk.md

Neon Python SDK

使用 neon-api 包在 Python 中以编程方式管理 Neon 时，请使用此文档。

链接：references/neon-python-sdk.md

Neon Auth

配置托管用户身份验证、UI 组件和身份验证方法，以及了解在 Next.js 和 React 应用中集成 Neon Auth 时的注意事项，请使用此文档。

链接：references/neon-auth.md

Neon Auth 也集成在 Neon JS SDK 中，因此根据你的使用场景，你可能会想改用 Neon JS SDK，而不是 Neon Auth。详情请参阅 references/connection-methods.md。

分支

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

要点：

• 分支是即时的写时复制克隆（不会完整复制数据）。
• 每个分支都有自己的计算端点。
• 使用 neonctl CLI 或 MCP 服务创建、检查和比较分支。

链接：references/branching.md

自动扩缩

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

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

缩容至零

当用户正在优化闲置成本，并讨论挂起／恢复行为（包括冷启动的权衡）时使用。

要点：

• 闲置的计算资源会自动挂起（默认为 5 分钟，可配置）（除非禁用——仅限 launch & scale 套餐）
• 挂起后执行的第一个查询通常会有冷启动开销（约数百毫秒）
• 计算资源挂起时，存储仍保持活动状态。

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