Pg Mcp Skills Free

SKILL.md

---
slug: pg-mcp-skills-free
name: pg-mcp-skills-free
version: 1.0.0
displayName: PG-MCP助手(免费版)
summary: PostgreSQL数据库管理与优化助手，通过MCP工具实现健康检查、索引调优、查询计划分析等。
license: Proprietary
edition: free
description: PG-MCP助手免费版是一套基于 MCP工具协议的 `PostgreSQL` 数据库管理与优化知识库，帮助开发者在不离开 Agent 对话的前提下完成数据库健康检查、索引优化、查询计划分析、模式查询与
  SQL 执行等日常运维任务。核心能力：提供 MCP工具可用性前置检查、六类常见意图的智能路由、写操作安全确认流程、只读模式兼容方案、长时间查询的性能保护策略
tags:
- 数据库
- 集成工具
- MCP工具
- 免费版
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: L3
pricing_model: per_use
suggested_price: 29.9
tools: ["read", "write", "exec"]
tags: "工具,效率,自动化"
---
# PG-MCP助手（免费版）

## 概述

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

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

## 核心能力

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

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

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

| 检查结果 | 处理方式 |
|----|----|
| 工具存在 | 正常执行后续流程 |
| 工具不存在 | 提示用户运行 `/setup-postgres-mcp` 完成部署 |

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

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

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

| 用户意图 | 参考文档 | 典型说法 |
|:-----|:-----|:-----|
| 安装部署 | setup-postgres-mcp.md | 安装、部署、配置、第一次用、连不上 |
| 健康检查 | pg-health.md | 健康检查、数据库状态、性能监控、连接数 |
| 索引优化 | pg-index-tuning.md | 索引优化、慢查询、性能调优、建索引 |
| 查询计划 | pg-query-plan.md | 执行计划、EXPLAIN、查询分析、为什么慢 |
| 模式查询 | pg-schema.md | 表结构、字段、关系、生成 SQL |
| 执行 SQL | pg-execute.md | 执行、查询、更新、插入、删除 |

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

### 能力三：写操作安全确认

执行写操作（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工具。

**典型提问模板**：

## 输入格式
| 参数名 | 类型 | 必填 | 说明 |
|---:|---:|---:|---:|
| input | string | 是 | PG-MCP助手(免费版)处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |

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

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

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

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

## 示例

### 前置检查流程

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

### 意图路由示例

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

### 写操作确认模板

```text
即将执行以下写操作：
# ...
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'` 为会话设置超时，避免意外执行了全表扫描等耗时查询拖垮数据库。

## 错误处理

| 错误场景(症状) | 可能原因 | 排查方法 | 对策 | 处理方式 |
|:-------:|:-------:|:-------:|:-------:|:-------:|
| MCP工具不可用 | 服务未部署或未配置 | 查看工具列表 | 运行 /setup-postgres-mcp | 对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令 |
| 连接超时 | 数据库不可达或防火墙拦截 | 测试网络连通性 | 执行ping命令测试网络连通性,检查防火墙和代理设置与安全组 | 对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令 |
| 权限不足 | 数据库用户权限缺失 | 查看 pg_roles | 授予必要权限 | 对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令 |
| 查询被自动取消 | statement_timeout 触发 | 查看超时设置 | 优化查询或调大超时 | 对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令 |
| 只读模式写操作失败 | MCP工具配置为只读 | 查看配置文件 | 改用 DBA 工单流程 | 对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令 |
## 常见问题

### 依赖详情

运行 `/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+）

### 第三方依赖
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:------|------:|:------|:------|
| LLM API | API | 必需 | 由Agent平台内置LLM提供 |
| postgres MCP server | 服务 | 必需 | 通过 /setup-postgres-mcp 部署 |
| `PostgreSQL` 客户端 | 工具 | 可选 | psql / pgAdmin / DBeaver 等 |

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

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

## 已知限制

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

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

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