Postgres MCP Pro Plus

<p align="center"> <strong>高级 PostgreSQL 数据库分析与优化套件</strong><br> <em>基于 <a href="https://github.com/crystaldba/postgres-mcp">crystaldba/postgres-mcp</a> 的扩展版本</em> </p>

🚀 主要特性

• 🔍 全面数据库分析：深入洞察模式结构、关系和性能
• ⚡ AI 驱动优化：使用数据库调优顾问 (DTA) 和 LLM 方法进行智能索引推荐
• 🩺 高级健康监控：多维度健康检查，带有预测分析
• 🔒 锁定与阻塞分析：实时检测并解决查询阻塞和死锁
• 🧹 智能维护：自动真空分析，带膨胀检测和维护计划
• 📊 性能智能：查询性能分析，资源使用优化
• 🔐 安全评估：全面的安全分析和建议
• 🐳 Docker 就绪：支持 Docker Compose 的容器化部署

📋 可用工具

核心数据库操作

工具名称	描述
list_schemas	列出所有模式，包括所有权和类型分类
list_objects	按模式浏览数据库对象（表、视图、序列、扩展）
get_object_details	对象详细分析，包括列、约束和索引
execute_sql	执行 SQL，带有安全控制（受限/非受限模式）

性能与优化

工具名称	描述
explain_query	使用 HypoPG 假设索引模拟的高级执行计划分析
get_top_queries	通过性能指标识别慢速和资源密集型查询
analyze_workload_indexes	从工作负载分析中进行 AI 驱动的索引推荐 (DTA/LLM)
analyze_query_indexes	针对特定查询集的目标索引优化 (最多 10 条查询)

健康与监控

工具名称	描述
analyze_db_health	综合健康检查：索引、连接、真空、序列、复制、缓冲缓存、约束
get_blocking_queries	高级阻塞分析，带有锁定层次可视化和解决方案建议
analyze_vacuum_requirements	综合真空分析，带膨胀检测和维护建议

高级分析

工具名称	描述
get_database_overview	企业级数据库评估，包括性能、安全性和关系分析
analyze_schema_relationships	模式依赖映射，带有视觉关系分析和耦合度量

🔧 工具详情及能力

🔍 数据库概览分析

企业级综合数据库评估

get_database_overview 工具提供多维分析：

• 📊 模式分析：完整的结构，包括表关系和依赖映射
• ⚡ 性能指标：查询性能、索引效率和资源使用模式
• 🔐 安全分析：用户权限、角色分配和安全配置评估
• 💾 存储分析：表大小、索引膨胀检测和磁盘使用优化
• 🩺 健康指标：连接健康、真空统计和系统性能指标

配置选项：

• max_tables (默认：500)：每个模式分析的最大表数以控制性能
• sampling_mode (默认：true)：大型数据集的统计抽样以优化执行时间
• timeout (默认：300)：最大执行时间，带有优雅的超时处理

🔒 高级阻塞查询分析

实时锁定冲突检测与解决

get_blocking_queries 工具具备企业级能力：

🎯 核心功能：

• 现代检测：使用 PostgreSQL 的 pg_blocking_pids() 函数进行准确的阻塞识别
• 锁定层次可视化：完整的阻塞链和进程关系
• 综合指标：进程细节、等待事件、时间、锁定类型和受影响的关系
• 智能建议：基于严重性的建议，带有具体的优化指导
• 生产就绪：设计用于企业数据库监控和性能故障排除

📋 分析输出：

• 进程信息：PID、用户、应用程序名称、客户端地址和连接详情
• 查询上下文：完整查询文本、执行时间和资源消耗
• 锁定详情：锁定类型、模式、受影响的数据库对象和等待事件
• 状态分析：进程状态、等待信息和阻塞持续时间
• 趋势分析：总结统计数据和模式识别
• 分类建议：🚨 关键、⚠️ 警告、💡 优化、🎯 热点警报

🔧 PostgreSQL 兼容性：

• 最低：PostgreSQL 9.6+（需要 pg_blocking_pids() 函数）
• 推荐：PostgreSQL 12+（增强的锁定监控功能）
• 最佳：PostgreSQL 14+（包括 pg_locks.waitstart 以实现精确的等待时间）

🧹 真空分析与维护

综合维护规划，带膨胀检测

analyze_vacuum_requirements 工具提供：

• 📈 膨胀分析：表和索引膨胀检测，带有严重性评估
• ⚙️ 自动真空配置：设置分析和优化建议
• 📊 性能影响：真空操作性能分析和瓶颈识别
• 🗓️ 维护规划：基于工作负载模式的智能调度建议
• 🚨 关键问题检测：立即关注维护相关问题的警报
• ⚡ 配置优化：真空参数调整建议

🗺️ 模式关系分析

高级依赖映射和可视化

analyze_schema_relationships 工具提供：

• 🔗 依赖映射：完整的跨模式关系可视化
• 📊 耦合分析：模式耦合度量和隔离评分
• 🎯 影响评估：模式修改的变更影响分析
• 📈 关系质量：外键关系质量和一致性评分
• 🔍 模式检测：常见反模式和架构建议

⚡ 索引优化智能

AI 驱动的索引推荐，带有高级算法

数据库调优顾问 (DTA) 功能：

• 🧠 帕累托优化：平衡性能和存储的多目标优化
• 📊 工作负载分析：从 pg_stat_statements 数据中的模式识别
• 💰 成本效益分析：存储预算限制，带有性能影响评估
• 🎯 查询特定调优：针对特定查询集的目标优化
• ⏱️ 时间限定分析：具有可配置运行时间限制的任意时间算法

LLM 驱动的优化：

• 🤖 智能分析：查询模式的自然语言理解
• 📝 上下文建议：易于理解的解释和实施指导
• 🔍 高级模式识别：复杂查询模式的检测和优化

🚀 快速开始

前提条件

• PostgreSQL 9.6+（推荐 PostgreSQL 12+，最佳 PostgreSQL 14+）
• Python 3.8+
• 可选：HypoPG 扩展用于假设索引分析

安装与设置

1. 环境配置

在项目根目录创建一个 .env 文件：

DATABASE_URI=postgresql://用户名:密码@localhost:5432/数据库名

2. 原生部署

# 启动 MCP 服务器（默认：stdio 传输，非受限模式）
./start.sh

# 启动读取模式，更安全的分析
./start.sh --access-mode restricted

# 启动 SSE 传输，用于 Web 集成
./start.sh --transport sse --sse-port 8099

# 启动外部可访问的 SSE 服务器
./start.sh --transport sse --sse-host 0.0.0.0 --sse-port 8099

# 显示所有可用选项
./start.sh --help

3. Docker 部署

# 使用 Docker Compose 启动
docker-compose up -d

# 查看日志
docker-compose logs -f postgres-mcp

4. 交互测试 (MCP Inspector)

# 终端 1：启动带有 SSE 传输的 MCP 服务器
./start.sh --transport sse --sse-port 8099

# 终端 2：启动 MCP Inspector（打开 Web 界面）
./start-inspector.sh

MCP Inspector 提供：

• 交互工具测试：使用 Web UI 测试所有数据库分析工具
• 参数探索：发现工具能力和配置选项
• 实时结果：在用户友好的界面中查看格式化的分析结果
• 文档：内置工具文档和使用示例

🔧 访问模式

非受限模式（默认）：

• 完整的 SQL 执行能力
• 数据库修改操作
• 完整的管理访问

受限模式（推荐用于分析）：

• 带有安全控制的只读操作
• SQL 注入防护
• 超时执行（默认 30 秒）
• 生产分析安全

📊 使用示例

基本服务器操作

# 显示帮助和配置选项
./start.sh --help

# 使用默认设置启动（stdio，非受限）
./start.sh

# 启动生产安全模式
./start.sh --access-mode restricted

# 启动 Web 服务器，用于 HTTP/SSE 集成
./start.sh --transport sse --sse-port 8099

健康检查示例

# 综合健康分析（通过 MCP 客户端）
analyze_db_health --health-type all

# 特定组件检查
analyze_db_health --health-type index,vacuum,buffer

# 性能优化工作流程
get_top_queries --sort-by resources
analyze_workload_indexes --method dta --max-index-size-mb 1000
get_blocking_queries

🏗️ 架构与组件

核心架构

postgres-mcp/
├── 🔧 server.py              # MCP 服务器及工具注册
├── 📊 database_health/       # 多维度健康监控
├── ⚡ explain/               # 查询执行计划分析
├── 🎯 index/                 # AI 驱动的索引优化
├── 📈 top_queries/           # 性能查询分析
├── 🔒 blocking_queries.py    # 锁定冲突分析
├── 🔍 database_overview.py   # 综合评估
├── 🗺️ schema_mapping.py      # 关系可视化
├── 🧹 vacuum_analysis.py     # 维护优化
└── 🛡️ sql/                   # SQL 执行框架

数据库健康组件

• 索引健康：无效、重复、膨胀和未使用的索引检测
• 连接健康：连接利用率和容量分析
• 真空健康：事务回绕和维护监控
• 序列健康：序列耗尽和溢出保护
• 复制健康：延迟监控和插槽管理
• 缓冲健康：表和索引的缓存命中率优化
• 约束健康：无效约束检测和修复

🤖 AI 集成功能

数据库调优顾问 (DTA)：

• 帕累托最优索引选择算法
• 多查询工作负载优化
• 预算约束推荐引擎
• 时间限定分析，带有任意时间方法

LLM 驱动的分析：

• 查询模式的自然语言理解
• 上下文优化建议
• 易于理解的解释和指导
• 高级模式识别能力

📈 最近改进

最新功能（最近提交）

• ✅ 全面工具分析：详细的分析文档，带有改进建议
• ✅ 增强可读性：所有模块的代码格式简化
• ✅ 健壮错误处理：真空分析中更好的 None 值处理
• ✅ 高级可视化：带有详细建议的阻塞查询分析增强
• ✅ 人类可读输出：重构分析工具，以更好地呈现文本
• ✅ 模式关系映射：新的模式依赖分析和可视化
• ✅ Docker 集成：带有 Docker Compose 支持的完整容器化
• ✅ 真空分析工具：全面的维护建议和膨胀检测

架构改进

• 模块化设计：增强组件分离和重用性
• 异步优化：通过更好的异步模式提高性能
• 安全框架：全面的 SQL 执行安全控制
• 错误恢复：强大的错误处理和优雅降级
• 性能扩展：优化大型数据库分析
• 增强启动脚本：灵活配置，带有全面验证和帮助系统

📚 文档与开发

高级文档

• 数据库工具分析：所有工具的全面分析，带有改进建议
• 工具改进路线图：优先级改进路线图（如果可用）
• 技术实现：详细的代码文档和 API 参考

扩展点

• 自定义健康检查：添加领域特定的健康监控
• 插件架构：扩展自定义分析工具
• 集成 API：连接外部监控系统
• 自定义可视化：添加专用报告和仪表板

🔒 安全与最佳实践

安全特性

• SQL 注入防护：全面的输入净化
• 访问模式控制：受限/非受限操作模式
• 超时执行：可配置的查询超时保护
• 参数验证：强大的输入验证和净化
• 错误处理：安全的错误报告，不泄露信息

生产指南

• 使用 受限模式 进行生产分析
• 配置适当的 超时值 以应对大型操作
• 监控 资源使用 在分析操作期间
• 实施 定期健康检查 以主动监控
• 定期审查 安全配置 和用户权限

📄 许可证

MIT 许可证

---

<p align="center"> <strong>🚀 Postgres MCP Pro Plus - 高级数据库智能</strong><br> <em>为数据库专业人士提供 AI 驱动的洞察和优化</em> </p>