neon-postgres

首先：使用父级 neon 技能了解 Neon、开始使用 Neon、Neon 开发最佳实践等。

如果尚未安装 neon 技能，请从 https://neon.com/docs/ai/skills/neon/SKILL.md 获取，或使用以下命令安装：

neon skills -s neon -y

Lakebase Postgres

Lakebase Postgres 是 Neon 的核心数据库。它运行在 lakebase 架构上——直接构建于云对象存储之上的 OLTP——将存储与计算分离，从而提供自动扩缩、分支、即时恢复和缩至零。它与 Postgres 完全兼容，可与支持 Postgres 的任何语言、框架或 ORM 配合使用。

无论通过 Neon 还是 Databricks 访问，使用的都是同一个数据库；本技能介绍通过 Neon 访问的方式。

登录、用户、会话和 @neondatabase/auth 属于 neon-auth。

实时查询、响应式 UI 和实时数据属于 neon-realtime。

设置流程

1. 选择组织和项目

如果已提供 DATABASE_URL（提示词、环境或代码库中），或 .neon 文件指向某个项目，请使用它。不要列出组织，也不要为架构工作创建第二个项目。

否则，使用 CLI（默认方式）或 MCP 服务列出组织和项目。让用户选择现有项目或创建新项目。

2. 获取连接字符串

如果已提供 DATABASE_URL，请使用它。不要通过 CLI 或 MCP 再获取一个连接字符串。

否则，使用 CLI（默认方式）、neon env pull 或 MCP 服务获取连接字符串。将其作为 DATABASE_URL 存入 .env。修改之前先读取该文件，以免覆盖已有值。

何时使用池化连接与直接连接

用例	连接类型
Web 应用、无服务器函数	池化（-pooler）
架构迁移	直接
pg_dump / pg_restore	直接
逻辑复制	直接
使用临时表的长时间运行分析	直接
需要 SET 或会话状态的管理任务	直接
LISTEN / NOTIFY	直接

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

保留现有的 ORM 和驱动程序。对于没有既定选择的新 TypeScript 架构工作，Drizzle 是一个建议：https://neon.com/docs/guides/drizzle.md。请参阅连接方式指南，根据运行时处理代码的方式选择合适的驱动程序：https://neon.com/docs/connect/choose-connection.md。

驱动程序说明：

• 在 Vercel 上，使用 node-postgres（npm install pg），搭配 Vercel Fluid 计算，并使用 import { attachDatabasePool } from "@vercel/functions";
• 在 Cloudflare 上，使用搭配 Cloudflare Hyperdrive 的 node-postgres
• 在 Neon Functions 上，使用 node-postgres，因为这些函数长期运行，并会在多个请求间复用连接池。
• 在无服务器和边缘环境中使用 @neondatabase/serverless 驱动程序（例如使用 Netlify 时）——一次性查询使用 HTTP 传输，事务支持使用 WebSocket。链接：https://neon.com/docs/serverless/serverless-driver.md

4. 设置架构

将架构和迁移作为代码管理。避免对数据库执行临时架构迁移，因为这类迁移难以管理。

如果你使用 ORM，请遵循该 ORM 管理架构和迁移的最佳实践。例如，如果使用 Drizzle，除非另有指示，否则只使用 Drizzle 管理架构和迁移。

分支

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

要点：

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

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

如需了解详细的分支创建工作流（普通分支与仅架构分支、从父分支重置、CLI/MCP 选择），请使用 neon-postgres-branches 技能。如果尚未安装，请从 https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md 获取，或通过以下命令安装：

neon skills -s neon-postgres-branches -y

迁移

在将迁移应用到生产环境之前，先在生产环境的分支上使用接近生产环境的数据进行测试。

运行迁移时，请使用**直接（非池化）**连接字符串，而非池化连接字符串。neon connection-string 默认返回直接连接字符串；请确保主机名不包含 -pooler 后缀。

故障排查与 Neon 专属性能诊断

在手动编写目录查询之前，请先使用 Neon 预定义的只读诊断功能。Neon CLI 的 neon inspect db 子命令和 Neon MCP 服务的 inspect_database 工具会运行相同的检查。

本节介绍 Neon 专属诊断工具、计算缓存行为和平台信号。如果证据表明需要进行通用 Postgres 工作，例如重写查询、选择索引、更改架构或解读计划节点，请加载 postgres-best-practices 技能，并在该工作流中沿用诊断证据。

文档：

• CLI：https://neon.com/docs/cli/inspect.md
• 查询性能：https://neon.com/docs/postgresql/query-performance.md
• pg_stat_statements：https://neon.com/docs/extensions/pg_stat_statements.md
• Neon Local File Cache：https://neon.com/docs/extensions/neon.md

选择 CLI 或 MCP

在终端访问和身份验证可用时，优先使用 Neon CLI：

neon inspect db <check>

CLI 会根据当前 Neon 上下文解析项目和分支。使用 --project-id、--branch 和 --database-name 覆盖这些设置。省略 --database-name 可检查该分支上的所有数据库。只有在直接检查 Postgres 数据库，而非通过 Neon API 解析数据库时，才使用 --db-url。

使用 Neon MCP 时，调用 inspect_database 并传入 projectId 和一个 check。仅在需要时传入 branchId、databaseName 或 computeId。省略 databaseName 可检查该分支上的所有数据库。只有当结果提示内容被截断时，才增大 limit。

选择诊断项

症状或问题	检查项
哪些关系占用了存储空间？	table-sizes、index-sizes
是否有未使用的索引，或表是否被频繁扫描？	unused-indexes、seq-scans
哪些查询已运行 5 分钟以上，或持有锁？	long-running-queries、locks
哪些查询消耗的总时间最多？	outliers
哪些查询运行次数最多？	calls
活跃数据是否适合放入计算资源缓存？	lfc-hit-rate、working-set
自动清理是否滞后，或是否有空间浪费？	vacuum-stats、bloat
逻辑复制是否正常？	replication-slots、subscriptions

不要混淆以下检查项：

• long-running-queries 报告当前正在运行且已运行超过 5 分钟的语句。
• outliers 按统计信息重置以来的累计执行时间对查询进行排名，而不是按平均延迟排名。
• calls 按相同统计历史期间的执行次数排名。

outliers 和 calls 需要 pg_stat_statements。lfc-hit-rate 和 working-set 需要 neon 扩展。如果检查项报告缺少扩展，请先征求许可，再运行建议的 CREATE EXTENSION 语句，因为安装扩展会修改数据库。

安全地解读结果

• 将 unused-indexes 视为候选列表，而不是删除索引的许可。删除前，请确认观测时间窗口、约束和工作负载。
• 对于小表，或读取表中大部分内容的查询，顺序扫描可能是合理的。添加索引前，请检查表大小、选择性和查询计划。
• bloat 是统计估算值。运行 VACUUM FULL、REINDEX 或类似修复操作前，请确认影响并规划好锁和维护安排。
• 计算资源重启时（包括缩放到零后的暂停），缓存和 Postgres 统计信息都会重置。解读新生成的 lfc-hit-rate、working-set、vacuum-stats 或 pg_stat_statements 结果前，请先运行有代表性的工作负载。
• 计算资源级检查（lfc-hit-rate、working-set 和 replication-slots）即使在检查所有数据库时也只运行一次。
• 任一数据库检查失败，都可能导致检查所有数据库的操作失败；请使用明确的 databaseName 重试相关检查，以隔离问题。

按查询检查 Neon 缓存行为

标准的 EXPLAIN (ANALYZE, BUFFERS) 会报告 Postgres 共享缓冲区活动，但不会显示 Neon 的本地文件缓存（LFC）或页面预取情况。对于安全的只读查询，请添加 Neon 的 FILECACHE 和 PREFETCH 选项：

EXPLAIN (ANALYZE, BUFFERS, PREFETCH, FILECACHE)
SELECT ...;

• File cache: hits 统计在计算资源的 LFC 中找到的页面数。
• File cache: misses 统计未在 LFC 中找到、而是从数据库存储中获取的页面数。
• Prefetch: hits、misses、expired 和 duplicates 显示 Neon 在执行器请求页面之前获取页面的效果。

FILECACHE 和 PREFETCH 会提供此查询的指标，且不需要 neon 扩展。相比之下，neon inspect db lfc-hit-rate 和 working-set 提供计算资源级统计信息，并且需要该扩展。

MCP 工具 explain_sql_statement 可以生成标准查询计划，但不支持 FILECACHE 或 PREFETCH 选项。若要通过 MCP 收集这些 Neon 专属指标，请使用 run_sql 执行上方明确标注为只读的 EXPLAIN 语句。

由于 ANALYZE 会执行语句，因此仅在执行安全时使用；不要自主运行会修改数据的 SQL。比较冷缓存和热缓存的运行结果时请务必谨慎，因为首次执行可能会填充缓存，从而显著改变后续结果。

性能工作流

1. 重现症状并记录其时间范围。
2. 运行上表中最精简且相关的 inspect 检查。
3. 在更改架构或计算资源之前，先确定具体查询。对于标准执行计划，使用 MCP explain_sql_statement；如果涉及 LFC 或预取行为，则使用上文针对 Neon 的 EXPLAIN。
4. 如果瓶颈与查询形式、索引、架构、锁定或 vacuum 行为有关，请加载 postgres-best-practices，并沿用检查结果和查询计划。Neon 计算资源、缓存、连接和平台方面的决策应留在此技能中处理。
5. 重新运行相同的检查和工作负载，以验证更改。

如果用户明确需要按平均执行时间对查询进行排名，并设置自定义阈值和数量限制，请使用 MCP list_slow_queries，而不是 inspect_database。除了上文明确提到的 EXPLAIN 情况外，只有在预定义检查无法回答问题时，才使用 run_sql 执行只读诊断 SQL。

自动扩缩容

当用户需要根据工作负载自动扩缩计算资源，并希望获得 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 系统复制数据，或从外部 Postgres 系统复制数据。

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

Lakebase 搜索

使用 Lakebase Search 进行语义搜索、全文搜索和混合搜索：

• 如需了解语义搜索，包括使用 Neon AI Gateway 生成嵌入，请阅读向量搜索。
• 如需了解使用 BM25 排名的全文搜索，请阅读全文搜索。
• 如需了解如何通过融合或重新排序组合语义和词法搜索结果，请阅读混合搜索。
• 如需了解如何通过 Drizzle ORM 管理上述功能，请阅读使用 Drizzle 管理 Lakebase Search。

链接：

• Lakebase Search 入门
• lakebase_vector 参考
• lakebase_text 参考

注意事项

连接池连接与直连：迁移、转储和复制时使用直连 URL

Neon 会为同一个数据库提供两个连接字符串：一个是连接池连接（主机名带有 -pooler 后缀），另一个是直连／非连接池连接（不带 -pooler 后缀）。neon env pull 会将它们分别写入 DATABASE_URL 和 DATABASE_URL_UNPOOLED。连接池连接会通过事务模式下的 PgBouncer 进行路由，而该模式不支持会话级操作。请根据用途选择合适的连接：

• 连接池连接（DATABASE_URL） — 应用程序的常规查询流量，尤其适用于无服务器和每个请求创建一个连接的工作负载。
• 直连（DATABASE_URL_UNPOOLED） — 架构迁移（Prisma Migrate、Drizzle Kit、Alembic 等）、pg_dump / pg_restore、逻辑复制、LISTEN/NOTIFY，以及依赖 SET 或其他会话状态的操作。

通过连接池连接执行迁移、转储或复制可能会失败，而且错误消息绝不会提到连接池：例如，Prisma Migrate 报错 prepared statement "s0" already exists；SET search_path 不会在其所属事务结束后继续生效，导致下一条查询报告 relation "mytable" does not exist；或者写入操作偶尔遇到只读事务（SQLSTATE 25006），因为连接池后端继承了之前某个客户端的状态。迁移工具通常可以同时接收两个连接字符串——例如 Prisma 的 directUrl 和 url——因此应将 directUrl 指向直连，而不是替换 DATABASE_URL，以免应用程序失去连接池功能。请参阅 https://neon.com/docs/connect/connection-pooling.md。