mcpField
D
db-connection-pooling

db-connection-pooling

github.com/hainrixz数据与数据库2180 次安装3 天前更新
代码仓库

关于 db-connection-pooling

用于检查数据库连接池配置风险的技能，重点识别可能导致连接耗尽的问题，涵盖无服务器环境直连 Postgres、事务池兼容性和连接池大小。

主要功能

  1. 01检测无服务器环境直连 Postgres
  2. 02检查事务池与会话功能冲突
  3. 03评估连接池与连接上限
  4. 04提供 Postgres 验证查询

适用场景

  1. 01审查无服务器数据库连接配置
  2. 02排查事务池中的预处理语句使用
  3. 03核对连接池及实例数是否超过后端上限

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hainrixz/claude-db --skill db-connection-pooling

安装后在 Claude Code 中输入/db-connection-pooling确认已加载。

详细介绍

db-connection-pooling (M15)

连接耗尽是导致生产环境中断的主要原因之一，完全属于 性能与扩展性（轴 performance）范畴。它为关系型数据库的 连接池 w10（以及每个 NoSQL 配置中的 连接 类别）提供信息。如今最常见的故障是无服务器函数各自打开一个直连，导致后端过载。

检查内容

  1. 无服务器 + 直连 Postgres — 函数／边缘运行时（Vercel/Lambda/Cloudflare/Netlify）在没有连接池的情况下直接连接 Postgres。每次冷启动都会打开一个连接；并发量激增时会超过 max_connections。建议使用事务模式连接池或无服务器驱动（Neon/@neondatabase/serverless、Supabase 连接池、PlanetScale HTTP）。
  2. 误用事务模式连接池 — 使用事务池化端点（PgBouncer transaction 模式、Supabase 端口 6543），同时依赖该模式会破坏的会话功能：服务端预处理语句、SET／会话 GUC、LISTEN/NOTIFY、会话级 advisory 锁。
  3. 连接池大小 — 应用连接池 max × 实例数量超过后端 max_connections，或者连接池过小，导致请求串行处理。

容量规划

  • 服务端连接上限大致是 vCPU 数量的较小倍数，而非峰值并发数。将 (cores*2) + effective_spindles 视为服务端可高效处理负载的后端连接上限，而非每个应用连接池的目标值。
  • 客户端连接池的大小应设为该上限，而非峰值请求并发数。后端连接数超过服务器的有效处理能力，只会增加上下文切换和锁争用；应在连接池排队，而不是在数据库排队。
  • 在 max_connections 以下预留余量 — 保留 superuser_reserved_connections（并为其他应用／复制留出空间），确保连接池饱和时管理员仍能连接。
  • PgBouncer 事务模式会将许多客户端连接复用到少量后端连接上，因此客户端连接池可以远超后端上限 — 但该模式会破坏会话级功能（服务端预处理语句、SET／会话 GUC、LISTEN/NOTIFY、会话范围的 advisory 锁）。

评分／轴

仅影响 性能（关系型数据库的 连接池 w10；NoSQL 配置中的 连接／连接池）。

Tier-0（静态）

检测运行时（依据 references/detection-signals.md 中的无服务器标记）以及客户端／驱动（pg、postgres、@neondatabase/serverless、@prisma/client、连接 URL 主机／端口）。标记来自无服务器环境的直连、与预处理语句用法同时出现的端口 6543／pgbouncer=true URL，以及连接池配置。后端 max_connections 和实时连接数属于运行时信息 → Tier-0 阶段为 needs_api。

Tier-1（验证查询，Postgres）

SELECT current_setting('max_connections') AS max_conn,
       count(*) AS open_conns,
       count(*) FILTER (WHERE state = 'idle') AS idle
FROM pg_stat_activity;

方法 connection_introspect。open_conns 接近 max_conn 时，确认连接耗尽问题，状态为 established。无服务器直连和连接池模式问题仅凭配置即可确认（directional）；其在负载下的影响需要 Tier-2 验证，若无 Tier-2 则为 needs_api。

问题项

依据 schema/finding.schema.json 输出问题项。示例：

  • M15.app.serverless_direct_pg — 无服务器函数直接连接 Postgres，未使用连接池（severity:4、warn、轴 performance、置信度 directional、fixable: proposed — 改用连接池／无服务器驱动）。
  • M15.app.prepared_stmt_on_txn_pooler — 通过事务模式连接池使用服务端预处理语句（severity:3、warn、directional、fixable: proposed）。
  • M15.app.pool_exceeds_max_connections — 连接池 × 实例数量 > 后端最大连接数（severity:3、warn、Tier-1 为 established／directional、fixable: proposed）。

每个问题项：evidence.observed 应逐字引用连接配置／驱动导入语句，并隐去凭据；verification.reproduce 应为上述引用 $DATABASE_URL 的目录查询；expected_impact 应标注区间和置信度（不得只给出百分比）。

诚实

  • 配置合理的连接池后，长时间运行的服务（单个 Node/Rails 进程）使用直连没问题——无服务器直连的结论仅适用于按调用运行时。
  • 绝不要引用无法观测到的连接数或故障概率；影响仅按区间划分，耗尽相关结论必须有 Tier-1/2 支持才能标记为 established。
  • 此处的所有修复都属于配置/架构调整 → proposed/advisory，绝不会是 auto。

评论

支持 Markdown