数据库连接助手（免费版）

概述

数据库是绝大多数业务系统的核心基础设施，但连接管理不当、事务设计缺陷、索引策略失误等问题往往在流量增长后才暴露。本助手将数据库常见陷阱整理为结构化知识库，帮助开发者在编码阶段就规避生产事故。

免费版聚焦于日常开发最高频的六大类陷阱：连接管理、事务处理、Schema 变更、查询模式、数据完整性、基础备份。每类陷阱均提供原因分析与可落地的对策。

核心能力

能力一：连接池陷阱识别

连接池耗尽是导致应用静默挂起的头号原因。本助手提供连接池配置清单与监控指标设计建议。

输入: 用户提供能力一：连接池陷阱识别所需的指令和必要参数。 处理: 解析能力一：连接池陷阱识别的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力一：连接池陷阱识别的响应数据,包含状态码、结果和日志。

能力二：事务安全指引

长事务持有锁并导致 MVCC 膨胀、不一致的锁顺序引发死锁、读改写场景的更新丢失——这些问题的根因和修复方式均可在本助手中查阅。

输入: 用户提供能力二：事务安全指引所需的指令和必要参数。 处理: 解析能力二：事务安全指引的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力二：事务安全指引的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

能力三：Schema 变更安全流程

加列、建索引、改列名等操作若处理不当会导致锁表或应用报错。本助手提供"先兼容代码、后变更结构"的两阶段发布清单。

输入: 用户提供能力三：Schema 变更安全流程所需的指令和必要参数。 处理: 解析能力三：Schema 变更安全流程的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力三：Schema 变更安全流程的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

能力四：查询模式审查

覆盖 N+1 查询、缺失索引、大 IN 子句、无界 SELECT 等 ORM 常见反模式。

输入: 用户提供能力四：查询模式审查所需的指令和必要参数。 处理: 解析能力四：查询模式审查的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力四：查询模式审查的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

已知限制

从应用层唯一检查的竞态条件，到时区存储、金额精度等数据正确性问题。

输入: 用户提供已知限制所需的指令和必要参数。 处理: 解析已知限制的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回已知限制的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

能力六：基础备份策略

逻辑备份与物理备份的取舍、时间点恢复的前置条件、备份验证的必要步骤。

输入: 用户提供能力六：基础备份策略所需的指令和必要参数。 处理: 解析能力六：基础备份策略的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力六：基础备份策略的响应数据,包含状态码、结果和日志。

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：面向开发者的数据、库连接与基础运维、覆盖连接池、索引等常见陷阱与、数据库连接助手免、费版是一套面向独、立开发者与小型团、队的数据库使用与、运维知识库、帮助用户在日常开、发中规避连接泄漏、事务死锁、索引失效等高频陷、核心能力、提供连接池配置建、事务隔离级别选择、Schema、变更安全流程、查询模式优化清单、数据完整性约束设、基础备份恢复策略、Use、when、需要数据库操作、SQL、数据存储管理时使、不适用于数据库架、构设计决策等。

使用场景

场景一：新项目数据库初始化

开发者搭建新服务时，参照本助手的连接池配置清单与索引设计原则，一次性建立规范的数据访问层。

场景二：线上故障初步定位

应用响应变慢时，按"连接池 → 慢查询 → 锁等待 → 死元组"的排查路径快速定位瓶颈。

场景三：SQL 代码审查

团队 Code Review 环节，使用查询模式审查清单逐条检查 SQL，避免 N+1 与无界查询上线。

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

本助手为纯知识库型 Skill，无需安装额外依赖。直接在 Agent 对话中描述你的数据库问题即可获取建议。

典型提问模板：

输入格式

我的应用使用 PostgreSQL，连接池配置为 max=10，高峰期出现请求超时，该如何排查？

我需要给一张 5000 万行的表添加带默认值的列，如何避免锁表？

ORM 生成的查询出现了 N+1 问题，有哪些解决思路？

Agent 会根据问题匹配对应的知识条目，输出"陷阱识别 → 原因分析 → 对策建议 → 验证方法"四段式回答。

示例

连接池配置参考

以 PostgreSQL 为例，使用 HikariCP 的推荐配置：

# HikariCP 推荐配置
maximumPoolSize: 20          # 根据 (核心数 * 2 + 有效磁盘数) 估算
minimumIdle: 10              # 空闲连接下限
connectionTimeout: 30000     # 获取连接超时 30s
idleTimeout: 600000          # 空闲连接超时 10min
maxLifetime: 1800000         # 连接最大生命周期 30min
leakDetectionThreshold: 60000 # 连接泄漏检测阈值 60s

事务隔离级别选择

最佳实践

实践一：事务保持简短

长事务会持有锁、阻止 VACUUM 清理死元组，导致表膨胀。建议将事务拆分为小批次，避免在事务中执行外部调用。

实践二：Schema 变更两阶段发布

1. 第一阶段：发布兼容代码（新列可空、新索引 CONCURRENTLY 创建）
2. 第二阶段：确认无报错后，发布使用新结构的代码

实践三：金额使用 DECIMAL

浮点数存储金额会产生精度丢失，应使用 DECIMAL 或整数分存储。

实践四：时区统一存 UTC

所有时间戳以 UTC 存储，仅在展示层转换为本地时区，避免跨时区混乱。

实践五：外键必须建索引

未建索引的外键会拖慢 JOIN 与级联删除，应在创建外键约束时同步创建索引。

实践六：批量操作分批次执行

大批量 INSERT/UPDATE/DELETE 应拆分为每批 1000-5000 条的小批次执行，避免长事务与锁表。

实践七：慢查询定期排查

开启慢查询日志（阈值建议 1 秒），定期分析 Top 10 慢查询并针对性优化索引或重写 SQL。

错误处理

常见问题

Q1：连接池大小设多少合适？

公式参考：池大小 = (核心数 * 2) + 有效磁盘数。但实际需结合 QPS、单查询耗时、可接受延迟综合调优。建议从 10-20 起步，通过压测调整。

Q2：为什么加列会导致锁表？

在旧版本数据库中，带默认值的加列操作会重写整张表。PostgreSQL 11+ 已优化此行为，但仍建议使用 NULL 默认值 + 回填 + 设置默认值三步法。

Q3：N+1 查询怎么发现？

开启 SQL 日志或使用 APM 工具，若同一请求内出现大量相似查询，基本可判定为 N+1。对策是预加载关联或批量查询。

Q4：备份能恢复才算备份

定期执行恢复演练，验证备份的完整性与可恢复性。仅备份不验证等于没有备份。

Q5：复制延迟导致读到旧数据怎么办？

对一致性敏感的读请求，路由到主库；或在副本查询前检查复制延迟，超阈值则回退主库。

Q6：COUNT 查询很慢怎么办？

大表的 COUNT(*) 需要扫描全表。替代方案：使用近似计数（PostgreSQL 的 pg_class.reltuples）、维护计数器表、或使用缓存。

Q7：如何防止 ORM 生成的 SQL 走偏？

开启 SQL 日志审查 ORM 生成的实际 SQL，定期检查是否有 N+1 查询、缺失索引的 WHERE 条件、不必要的全表加载。

Q8：服务器less 环境如何管理数据库连接？

Serverless 函数每次调用可能新建连接，导致连接数暴增。推荐使用连接代理（如 PgBouncer）复用连接，或使用云数据库的 Proxy 服务。

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• 数据库: PostgreSQL / MySQL / SQLite 等主流关系型数据库

依赖详情

API Key 配置

• 本免费版为纯知识库型 Skill，自身不需要 API Key
• 若 Agent 需要连接实际数据库执行诊断命令，相关凭据由用户自行配置于环境变量中
• 禁止在 SKILL.md 或脚本中硬编码数据库凭据

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分诊断功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent输出数据库设计与运维建议

免费版限制

本免费体验版限制以下高级功能：

• 分库分表策略设计（仅专业版提供）
• 复制高可用与故障转移方案（仅专业版提供）
• 深度性能调优与执行计划分析（仅专业版提供）
• 自动化备份恢复编排（仅专业版提供）
• 监控告警指标体系设计（仅专业版提供）

解锁全部功能请使用专业版：db-connector-pro

输出格式

{
  "success": true,
  "data": {
    "result": "数据库连接助手(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "db connector"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}