使用 Neon/Lakebase Postgres…

在已有 DATABASE_URL 或需要处理 Neon Postgres 的连接、SQL、schema、检查、搜索时，按此流程操作。

适用场景

解决思路

1. 先使用父级 `neon` 技能了解 Neon 概览、入门和开发最佳实践；若未安装，从 https://neon.com/docs/ai/skills/neon/SKILL.md 获取，或运行 `neon skills -s neon -y` 安装。
2. 明确 Lakebase Postgres 是 Neon 核心数据库，兼容 Postgres，支持任意语言、框架或 ORM；登录、用户、session 和 `@neondatabase/auth` 交给 `neon-auth`。
3. 选择组织和项目：若已有 `DATABASE_URL`（提示、环境变量或仓库中）或 `.neon` 文件指向项目，直接使用；不要为了 schema 工作重新列出组织或创建第二个项目。
4. 若没有项目：使用 CLI（默认）或 MCP server 列出组织和项目，让用户选择现有项目或创建新项目。
5. 获取连接串：若已有 `DATABASE_URL` 就直接用，不要通过 CLI/MCP 再取一个。
6. 若没有连接串：使用 CLI（默认）、`neon env pull` 或 MCP server 获取；存入 `.env` 的 `DATABASE_URL`；修改前先读取文件，避免覆盖已有值。
7. 按用途选 pooled vs direct：Web 应用或无服务器函数用 pooled（`-pooler`）；schema 迁移、`pg_dump`/`pg_restore`、逻辑复制、带临时表的长时分析、需要 `SET` 或 session 状态的管理任务、`LISTEN`/`NOTIFY` 用 direct。
8. 选择连接方法和驱动：保留现有 ORM 和驱动。
9. 如果没有既定选择且是新的 TypeScript schema 工作，建议 Drizzle：https://neon.com/docs/guides/drizzle.md。
10. 根据运行时如何处理代码，参考连接方法指南选择正确驱动：https://neon.com/docs/connect/choose-connection.md。
11. Vercel 上使用 `node-postgres`（`npm install pg`），配合 Vercel Fluid compute 和 `import { attachDatabasePool } from "@vercel/functions";`。
12. Cloudflare 上使用 `node-postgres`，配合 Cloudflare Hyperdrive。
13. Neon Functions 上使用 `node-postgres`，因为函数长运行并跨请求复用连接池。
14. 无服务器和边缘环境（例如 Netlify）使用 `@neondatabase/serverless` 驱动：一次性查询用 HTTP transport，事务支持用 WebSocket。链接 https://neon.com/docs/serverless/serverless-driver.md。
15. 设置 schema：把 schema 和迁移作为代码管理，避免对数据库运行临时 schema 迁移。
16. 若使用 ORM，遵循 ORM 最佳实践；例如 Drizzle 只用于 schema 和迁移管理，除非另有指示。
17. 分支：用于隔离环境、迁移测试、预览部署或分支生命周期自动化。
18. 分支要点：分支是即时 copy-on-write 克隆，不复制全量数据；每个分支有自己的 compute endpoint；用 Neon CLI 或 MCP server 创建、检查和比较分支。链接 https://neon.com/docs/introduction/branching.md。
19. 详细分支创建流程（普通 vs schema-only 分支、reset-from-parent、CLI/MCP 选择）使用 `neon-postgres-branches` 技能；若未安装从 https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md 获取，或运行 `neon skills -s neon-postgres-branches -y` 安装。
20. 迁移：在生产的某个分支上，用接近生产的数据测试迁移，再应用到生产。
21. 运行迁移时使用 direct（非 pooled）连接串；`neon connection-string` 默认返回 direct，确保 hostname 不含 `-pooler` 后缀。
22. 故障排查和 Neon 专用性能：先使用 Neon 预定义只读诊断，再手写 catalog 查询；Neon CLI `neon inspect db` 子命令和 Neon MCP server 的 `inspect_database` 工具运行相同检查。
23. 当证据指向通用 Postgres 工作（重写查询、选择索引、修改 schema、解释 plan 节点）时，加载 `postgres-best-practices` 技能，并带上诊断证据；Neon compute、cache、连接和平台决策留在本技能。
24. 选择 CLI 或 MCP：有终端和认证时优先用 Neon CLI：`neon inspect db <check>`。
25. CLI 默认从当前 Neon 上下文解析项目和分支；用 `--project-id`、`--branch`、`--database-name` 覆盖；省略 `--database-name` 表示检查分支上的每个数据库；只在直接检查 Postgres 数据库而非通过 Neon API 解析时用 `--db-url`。
26. 使用 Neon MCP 时，调用 `inspect_database`，传入 `projectId` 和一个 `check`；仅在需要时传 `branchId`、`databaseName` 或 `computeId`；省略 `databaseName` 检查分支上所有数据库；仅当结果提示被截断时增大 `limit`。
27. 按诊断选择检查：哪些 relation 占存储用 `table-sizes`、`index-sizes`；索引未使用或表被大量扫描用 `unused-indexes`、`seq-scans`；什么已运行 5+ 分钟或持锁用 `long-running-queries`、`locks`；哪些查询总耗时最多用 `outliers`；哪些查询运行最频繁用 `calls`；活跃数据是否适合 compute cache 用 `lfc-hit-rate`、`working-set`；autovacuum 是否落后或空间浪费用 `vacuum-stats`、`bloat`；逻辑复制是否健康用 `replication-slots`、`subscriptions`。
28. 不要混淆检查：`long-running-queries` 报告当前正在运行超过 5 分钟的语句；`outliers` 按统计重置以来累计执行时间排序，不按平均延迟排序；`calls` 按同一统计历史的执行次数排序。
29. `outliers` 和 `calls` 需要 `pg_stat_statements`；`lfc-hit-rate` 和 `working-set` 需要 `neon` 扩展；若检查提示缺少扩展，先询问再运行建议的 `CREATE EXTENSION` 语句，因为安装扩展会修改数据库。
30. 安全解释结果：`unused-indexes` 只是候选列表，不是删除索引的许可；删除前确认观察窗口、约束和工作负载。
31. 顺序扫描对小表或读取大部分表的查询可能是正确的；添加索引前检查表大小、选择性和查询计划。
32. `bloat` 是统计估算；执行 `VACUUM FULL`、`REINDEX` 或类似修复前确认影响并规划锁或维护。
33. Cache 和 Postgres 统计在 compute 重启时重置，包括 scale-to-zero 挂起；解释新的 `lfc-hit-rate`、`working-set`、`vacuum-stats` 或 `pg_stat_statements` 结果前，先运行代表性工作负载。
34. Compute 级检查（`lfc-hit-rate`、`working-set`、`replication-slots`）即使检查每个数据库也只运行一次。
35. 一个数据库失败可能导致 all-databases 检查失败；用显式 `databaseName` 重试相关检查以隔离问题。
36. 按查询检查 Neon cache：标准 `EXPLAIN (ANALYZE, BUFFERS)` 只报告 Postgres shared-buffer 活动，不显示 LFC 或 page prefetching；对安全只读查询添加 Neon 的 `FILECACHE` 和 `PREFETCH` 选项：`EXPLAIN (ANALYZE, BUFFERS, PREFETCH, FILECACHE) SELECT ...;`。
37. `File cache: hits` 统计 compute LFC 中的页；`File cache: misses` 统计 LFC 未命中并从数据库存储获取的页；`Prefetch: hits`、`misses`、`expired`、`duplicates` 显示 Neon 在 executor 请求前预取页的效果。
38. `FILECACHE` 和 `PREFETCH` 提供该查询的指标且不需要 `neon` 扩展；对比之下 `neon inspect db lfc-hit-rate` 和 `working-set` 提供 compute 级统计且需要该扩展。
39. MCP `explain_sql_statement` 可生成标准 plan，但不暴露 `FILECACHE` 或 `PREFETCH` 选项；要通过 MCP 收集这些 Neon 专用指标，用 `run_sql` 执行上面的显式只读 `EXPLAIN` 语句。
40. 因为 `ANALYZE` 会执行语句，只在执行安全时使用；不要对 mutating SQL 自主运行；仔细比较冷缓存和热缓存运行，因为首次执行会填充缓存并显著改变后续结果。
41. 性能工作流：1) 复现症状并记录时间窗口；2) 从上表运行最小相关 `inspect` 检查；3) 在修改 schema 或 compute 前定位具体查询，用 MCP `explain_sql_statement` 获取标准 plan，或在 LFC/prefetch 重要时用 Neon 专用 `EXPLAIN`；4) 若瓶颈是查询形态、索引、schema、锁或 vacuum 行为，加载 `postgres-best-practices` 并带上检查结果和查询计划；Neon compute、cache、连接和平台决策留在本技能；5) 重跑相同检查和工作负载验证变更。
42. 当用户明确需要按平均执行时间排序且带自定义阈值和限制时，用 MCP `list_slow_queries` 而不是 `inspect_database`；除上述显式 `EXPLAIN` 情况外，仅当预定义检查无法回答问题时，才用 `run_sql` 执行只读诊断 SQL。
43. Autoscaling：需要 compute 随工作负载自动伸缩并获取 CU 规格和运行时行为指导时使用。链接 https://neon.com/docs/introduction/autoscaling.md。
44. Scale to Zero：优化空闲成本并讨论 suspend/resume 与冷启动权衡时使用；空闲 compute 默认 5 分钟后自动 suspend，超时可配置，只有 Launch 和 Scale 计划可以禁用 suspend；suspend 后首次查询通常有冷启动惩罚（约数百 ms）；存储保持活跃。链接 https://neon.com/docs/introduction/scale-to-zero.md。
45. Instant Restore：需要 point-in-time recovery 或不想走传统备份恢复流程时使用；历史窗口取决于计划限制；可从历史时间点创建分支；Time Travel 查询可用于历史检查工作流。链接 https://neon.com/docs/introduction/branch-restore.md。
46. Read Replicas：读密集工作负载需要专用只读 compute 且不复制存储时使用；副本是共享同一存储的只读 compute endpoint；创建快且可独立于主 compute 扩展；典型用例：分析、报表、读密集 API。链接 https://neon.com/docs/introduction/read-replicas.md。
47. Connection Pooling：无服务器或高并发环境需要安全可扩展的 Postgres 连接管理时使用；Neon pooling 使用 PgBouncer；在 endpoint hostname 加 `-pooler` 使用 pooled 连接；在突发并发的无服务器运行时尤其重要。链接 https://neon.com/docs/connect/connection-pooling.md。
48. IP Allow Lists：需要按受信网络、IP 或 CIDR 范围限制数据库访问时使用。链接 https://neon.com/docs/introduction/ip-allow.md。
49. Logical Replication：集成 CDC 管道、外部 Postgres 同步或基于复制的数据移动时使用；Neon 支持原生逻辑复制工作流；可用于与外部 Postgres 系统之间复制。链接 https://neon.com/docs/guides/logical-replication-guide.md。
50. Lakebase Search：需要语义、全文或混合搜索时使用；语义搜索读 `references/vector-search.md`；BM25 排名的全文搜索读 `references/full-text-search.md`；组合语义和词法结果读 `references/hybrid-search.md`。链接：Lakebase Search 入门 https://neon.com/docs/ai/lakebase-search-get-started；`lakebase_vector` 参考 https://neon.com/docs/extensions/lakebase-vector；`lakebase_text` 参考 https://neon.com/docs/extensions/lakebase-text。
51. Gotcha pooled vs direct：Neon 对同一数据库给两个连接串：pooled（hostname 带 `-pooler` 后缀）和 direct/unpooled（不带 `-pooler`）。`neon env pull` 写入 `DATABASE_URL` 和 `DATABASE_URL_UNPOOLED`。Pooled 经 PgBouncer transaction mode 路由，不支持 session 级操作。
52. 选择：Pooled（`DATABASE_URL`）用于应用正常查询流量，尤其是无服务器和每请求一连接的工作负载；Direct（`DATABASE_URL_UNPOOLED`）用于 schema 迁移（Prisma Migrate、Drizzle Kit、Alembic 等）、`pg_dump`/`pg_restore`、逻辑复制、`LISTEN`/`NOTIFY`，以及任何依赖 `SET` 或其他 session 状态的操作。
53. 在 pooled 连接上运行迁移、dump 或复制可能失败，且错误不会指明 pooling：例如 Prisma Migrate 的 `prepared statement "s0" already exists`；`SET search_path` 不能持久到自身事务之后，导致下一查询报 `relation "mytable" does not exist`；写操作间歇性命中只读事务（`SQLSTATE 25006`），该 pooled backend 继承自更早客户端。
54. 迁移工具通常同时接收两个连接串——例如 Prisma 的 `directUrl` 和 `url`——把 `directUrl` 指向 direct 串，而不是交换 `DATABASE_URL` 并让应用失去 pooling。参见 https://neon.com/docs/connect/connection-pooling.md。

适用边界 · 注意事项

• 新后端、Auth、文件、Functions 和 LLM 调用不属于本技能，应使用父级 `neon` 技能。
• 登录、用户、session 和 `@neondatabase/auth` 应使用 `neon-auth`。
• 若问题本质是通用 Postgres 查询、索引、schema、锁或 vacuum 优化，应加载 `postgres-best-practices`；非 Neon/Lakebase Postgres 访问路径不适用本技能。