PG-MCP助手（免费版）

概述

PostgreSQL 数据库的日常运维涉及健康检查、索引调优、查询计划分析、表结构查询、SQL 执行等多种操作。传统方式需要切换到 psql 客户端或图形工具，打断了开发节奏。通过 MCP工具协议，这些操作可以在 Agent 对话中直接完成，实现"对话即运维"的体验。

本免费版聚焦于开发与测试环境最高频的六类运维场景：安装部署、健康检查、索引优化、查询计划、模式查询、SQL 执行。每类场景均提供意图识别规则、工具调用模板与安全约束。

核心能力

能力一：MCP工具可用性前置检查

所有 PostgreSQL 操作依赖 MCP工具（如 get_database_health、analyze_query_plan 等）。执行任何操作前，必须先确认这些工具是否可用，避免后续流程中断。

判断方法：检查当前可用的 MCP工具列表中是否存在 postgres 相关工具。

输入: 用户提供能力一：MCP工具可用性前置检查所需的指令和必要参数。 处理: 解析能力一：MCP工具可用性前置检查的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回能力一：MCP工具可用性前置检查的响应数据,包含状态码、结果和日志。

能力二：六类意图智能路由

根据用户输入判断意图，匹配对应的参考文档执行指令。意图不明确时先询问用户具体需求。

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

能力三：写操作安全确认

执行写操作（UPDATE、DELETE、DROP 等）前必须向用户展示将要执行的 SQL 并请求确认，避免误操作导致数据丢失。

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

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

能力四：只读模式兼容

若 MCP工具配置为只读模式，只能执行 SELECT 查询。本助手会自动识别只读模式并拒绝写操作，给出友好提示。

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

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

能力五：长时间查询性能保护

长时间运行的查询会被自动限制，避免影响数据库整体性能。本助手提供超时设置建议与慢查询识别方法。

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

• 执行此能力时使用input_params参数,支持创建/查询/导出操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：数据库管理与优化、工具实现健康检查、索引调优、查询计划分析等、助手免费版是一套、工具协议的、知识库、帮助开发者在不离、Agent、对话的前提下完成、数据库健康检查、查询计划分析、模式查询与、执行等日常运维任、核心能力、六类常见意图的智、写操作安全确认流、只读模式兼容方案、长时间查询的性能、保护策略等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：开发环境日常巡检

开发者每天早晨通过"健康检查"意图快速查看数据库状态，包括连接数、缓存命中率、死元组比例等关键指标。

场景二：慢查询快速定位

线上反馈某接口响应慢，通过"查询计划"意图分析对应 SQL 的执行计划，识别全表扫描、索引失效等问题。

场景三：表结构快速查询

新接手项目时，通过"模式查询"意图快速了解数据库表结构、字段含义、外键关系，加速上手。

场景四：开发阶段 SQL 调试

编写复杂 SQL 时，通过"执行 SQL"意图在开发库中验证语法与结果，避免直接在生产环境试错。

不适用场景

以下场景PG-MCP助手(免费版)不适合处理：

• 数据库架构设计决策
• NoSQL选型
• 数据仓库ETL设计

触发条件

需要数据库操作、SQL查询、数据存储管理时使用。不适用于非本工具能力范围的需求。

快速开始

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

本助手需要配合 MCP工具使用。请确保已安装并配置 postgres 相关的 MCP工具。

典型提问模板：

输入格式

帮我检查一下数据库的健康状态，看看有没有异常

这条查询很慢，帮我分析一下执行计划：SELECT * FROM orders WHERE user_id = 123

我想看一下 orders 表的结构，有哪些字段和索引

Agent 会根据输入识别意图，调用对应的 MCP工具，并返回结构化的分析结果与建议。

示例

前置检查流程

1. 扫描当前可用的 MCP工具列表
2. 检查是否存在 postgres 相关工具（如 get_database_health、analyze_query_plan）
3. 若存在 → 正常执行
4. 若不存在 → 提示：
   "PostgreSQL MCP工具尚未连接，请先运行 /setup-postgres-mcp 完成部署和配置。"

意图路由示例

用户输入："数据库最近很慢，帮我看看"
# ...
意图识别：
- "慢" → 可能是索引优化或查询计划
- 询问用户："您是想分析具体慢查询的执行计划，还是想整体调优索引？"
# ...
用户选择后，加载对应参考文档执行。

写操作确认模板

即将执行以下写操作：
# ...
SQL: UPDATE users SET status = 'inactive' WHERE last_login < '2024-01-01';
预计影响行数：约 1200 行
# ...
请确认是否执行？（输入"确认"继续，输入"取消"中止）

最佳实践

实践一：永远先做前置检查

不要假设 MCP工具一定可用。环境切换、配置变更、服务重启都可能导致工具失效。每次执行操作前都应做前置检查。

实践二：写操作必须二次确认

即使是开发环境，写操作也应展示 SQL 并请求确认。自动化批量操作尤其危险，一行错误的 UPDATE 可能毁掉整张表。

实践三：生产环境优先只读模式

生产环境的 MCP工具应配置为只读模式，写操作通过工单系统审批后由 DBA 执行。本助手会自动识别只读模式并拒绝写操作。

实践四：慢查询先看执行计划

遇到慢查询不要急于加索引。先用"查询计划"意图分析 EXPLAIN 输出，确认是否真的走索引、扫描行数多少、是否有嵌套循环。

实践五：模式查询善用系统视图

PostgreSQL 的 information_schema 与 pg_catalog 提供了丰富的元数据查询视图。本助手优先使用这些标准视图，兼容性最好。

实践六：长时间查询设置超时

通过 SET statement_timeout = '30s' 为会话设置超时，避免意外执行了全表扫描等耗时查询拖垮数据库。

错误处理

常见问题

依赖详情

运行 /setup-postgres-mcp 命令，按照向导完成部署与配置。部署过程包括安装 MCP server、配置数据库连接、注册工具到 Agent。

Q2：MCP工具支持哪些 PostgreSQL 版本？

支持 PostgreSQL 10 及以上版本。部分高级功能（如并行查询计划分析）需要 13 及以上版本。

Q3：写操作为什么必须确认？

数据库写操作具有不可逆性（尤其是 DELETE、DROP）。即使有备份，恢复也耗时费力。二次确认是最低成本的安全保障。

Q4：只读模式能执行哪些操作？

只读模式只能执行 SELECT 查询，包括健康检查、索引分析、查询计划、模式查询等。UPDATE、DELETE、INSERT、DROP、ALTER 等写操作会被拒绝。

Q5：查询计划中的 Seq Scan 一定有问题吗？

不一定。小表的 Seq Scan 比索引扫描更快。只有当 Seq Scan 出现在大表上，或估算行数远超实际行数时，才需要优化。

Q6：如何查看当前数据库连接数？

通过健康检查意图，调用 get_database_health 工具，会返回当前连接数、最大连接数、活跃连接数等指标。

依赖说明

运行环境

• Agent 平台: 支持SKILL.md与 MCP工具的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• 数据库: PostgreSQL 10+（推荐 13+）

第三方依赖

API Key 配置

• 本免费版为知识库型 Skill，自身不需要 API Key
• 数据库连接凭据由 MCP server 配置文件管理，应存储于密钥管理服务中
• 禁止在 SKILL.md 或脚本中硬编码数据库凭据

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent调用MCP工具完成数据库运维

已知限制

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

• 生产级性能调优与执行计划深度分析（仅专业版提供）
• 自动化索引推荐与冗余索引清理（仅专业版提供）
• 数据库迁移与版本升级方案（仅专业版提供）
• 多数据库实例统一管理（仅专业版提供）
• 高可用与故障转移监控（仅专业版提供）

解锁全部功能请使用专业版：pg-mcp-skills-pro

输出格式

{
  "success": true,
  "data": {
    "result": "PG-MCP助手(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "pg mcp skills"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}