MCP Postgresql Ops

🚀 PostgreSQL操作与监控MCP服务器

MCP-PostgreSQL-Ops 是一款专业的MCP服务器，用于对PostgreSQL数据库进行操作、监控和管理。它支持PostgreSQL 12 - 17版本，可通过自然语言查询实现全面的数据库分析、性能监控以及智能维护建议。大部分功能可独立运行，但在安装 pg_stat_statements 和（可选）pg_stat_monitor 扩展后，高级查询分析功能将得到增强。

✨ 主要特性

• ✅ 零配置：可直接与PostgreSQL 12 - 17版本配合使用，自动检测版本。
• ✅ 自然语言交互：支持使用自然语言提问，例如 “显示慢查询” 或 “分析表膨胀情况”。
• ✅ 生产环境安全：仅执行只读操作，兼容RDS/Aurora，普通用户权限即可使用。
• ✅ 扩展增强：可选安装 pg_stat_statements 和 pg_stat_monitor 扩展，以实现高级查询分析。
• ✅ 全面的数据库监控：提供性能分析、表膨胀检测和维护建议。
• ✅ 智能查询分析：通过集成 pg_stat_statements 和 pg_stat_monitor 识别慢查询。
• ✅ 模式与关系发现：探索数据库结构，提供详细的关系映射。
• ✅ VACUUM与自动清理智能分析：实时监控维护操作并分析其有效性。
• ✅ 多数据库操作：无缝进行跨数据库分析和监控。
• ✅ 企业级适用：安全的只读操作，兼容RDS/Aurora。
• ✅ 开发者友好：代码结构简单，易于定制和扩展工具功能。

🔧 高级功能

• 支持版本感知的I/O统计（在PostgreSQL 16+版本中增强）。
• 实时监控连接和锁状态。
• 分析后台进程和检查点。
• 监控复制状态和WAL日志。
• 分析数据库容量和表膨胀情况。

🚀 快速开始

⚠️ 重要提示

docker-compose.yml 中包含的 postgresql 容器仅用于快速启动测试。您可以根据需要调整环境变量，连接到自己的PostgreSQL实例。

💡 使用建议

若要使用自己的PostgreSQL实例而非内置测试容器，请按以下步骤操作：

• 更新 .env 文件中的目标PostgreSQL连接信息（请参考 POSTGRES_HOST、POSTGRES_PORT、POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB）。
• 在 docker-compose.yml 中注释掉（禁用）postgres 和 postgres-init-extensions 容器，以避免启动内置测试数据库。

1. 环境设置

⚠️ 重要提示

虽然超级用户权限可以访问所有数据库和系统信息，但MCP服务器使用普通用户权限也能执行基本的监控任务。

git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

### 检查并修改.env文件
cp .env.example .env
vim .env

### 无需修改默认值，但如果使用自己的PostgreSQL服务器，请编辑以下内容：
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=15432  # 主机访问的外部端口（映射到内部5432）
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme!@34
POSTGRES_DB=ecommerce # 默认连接的数据库。超级用户可以访问所有数据库。

⚠️ 重要提示

PGDATA=/data/db 是为Percona PostgreSQL Docker镜像预先配置的，该镜像需要此特定路径以确保正确的写入权限。

2. 启动演示容器

# 启动所有容器，包括内置的PostgreSQL进行测试
docker-compose up -d

# 替代方案：如果使用自己的PostgreSQL实例
# 在docker-compose.yml中注释掉postgres和postgres-init-extensions服务
# 然后使用自定义配置：
# docker-compose -f docker-compose.custom-db.yml up -d

⚠️ 重要提示

初始环境设置需要几分钟时间，因为容器按以下顺序启动：

1. PostgreSQL 容器首先启动并初始化数据库。
2. PostgreSQL扩展 容器安装扩展并创建全面的测试数据（约83K条记录）。
3. MCP服务器 和 MCPO代理 容器在PostgreSQL准备好后启动。
4. OpenWebUI 容器最后启动，加载Web界面可能需要额外的时间。

💡 使用建议

运行 docker-compose up -d 后等待2 - 3分钟再访问OpenWebUI，以确保所有服务完全初始化。

🔍 检查容器状态（可选）：

# 监控容器启动进度
docker-compose logs -f

# 检查所有容器是否正在运行
docker-compose ps

# 验证PostgreSQL是否准备好
docker-compose logs postgres | grep "ready to accept connections"

3. 访问OpenWebUI

访问地址：http://localhost:3003/

• 由 swagger 提供的MCP工具功能列表可在MCPO API文档URL中找到。
  • 例如：http://localhost:8003/docs

4. 在OpenWebUI中注册工具

1. 使用管理员账户登录OpenWebUI。
2. 从顶部菜单中选择 “设置” → “工具”。
3. 输入 postgresql-ops 工具地址（例如，http://localhost:8003/postgresql-ops）以连接MCP工具。
4. 设置Ollama或OpenAI。

5. 完成！

恭喜！ 您的MCP PostgreSQL操作服务器现已可以使用。您可以开始使用自然语言查询探索您的数据库。

🚀 尝试以下示例查询：

• “显示当前活动连接”
• “系统中最慢的查询有哪些？”
• “分析所有数据库中的表膨胀情况”
• “显示数据库大小信息”
• “哪些表需要进行VACUUM维护？”

💻 使用示例

Claude桌面集成

（推荐）将以下内容添加到您的Claude桌面配置文件中：

{
  "mcpServers": {
    "postgresql-ops": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

（可选）使用本地源代码运行：

{
  "mcpServers": {
    "postgresql-ops": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.mcp_postgresql_ops.mcp_main"],
      "env": {
        "PYTHONPATH": "/path/to/MCP-PostgreSQL-Ops",
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

独立运行MCP服务器

使用Pypi和uvx（推荐）

# 标准输入输出模式
uvx --python 3.11 mcp-postgresql-ops \
  --type stdio

# HTTP模式
uvx --python 3.11 mcp-postgresql-ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8080 \
  --log-level DEBUG

（可选）配置多个PostgreSQL实例

{
  "mcpServers": {
    "Postgresql-A": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "a.foo.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    },
    "Postgresql-B": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "b.bar.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    }
  }
}

使用本地源代码

# 标准输入输出模式
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops
python -m src.mcp_postgresql_ops.mcp_main \
  --type stdio

# HTTP模式
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops
python -m src.mcp_postgresql_ops.mcp_main \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8080 \
  --log-level DEBUG

📚 详细文档

环境变量

⚠️ 重要提示

POSTGRES_DB 是在未指定特定数据库时操作的默认目标数据库。在Docker环境中，如果设置为非默认名称，该数据库将在PostgreSQL首次启动时自动创建。

💡 使用建议

内置的PostgreSQL容器使用端口映射 15432:5432，其中：

• POSTGRES_PORT = 15432：主机访问和MCP服务器连接的外部端口。
• DOCKER_INTERNAL_PORT_POSTGRESQL = 5432：容器内部端口（PostgreSQL默认）。
• 使用外部PostgreSQL服务器时，请将 POSTGRES_PORT 设置为与服务器实际端口匹配。

先决条件

所需的PostgreSQL扩展

⚠️ 重要提示

有关更多详细信息，请参阅 工具兼容性矩阵。

💡 使用建议

大多数MCP工具无需任何PostgreSQL扩展即可工作。一些高级性能分析工具需要以下扩展：

-- 查询性能统计（仅 `get_pg_stat_statements_top_queries` 需要）
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 高级监控（可选，`get_pg_stat_monitor_recent_queries` 使用）
CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;

⚠️ 重要提示

对于新的PostgreSQL安装，在 postgresql.conf 中添加以下内容：

shared_preload_libraries = 'pg_stat_statements'

然后重启PostgreSQL并运行上述 CREATE EXTENSION 命令。

• pg_stat_statements 仅用于慢查询分析工具。
• pg_stat_monitor 是可选的，用于实时查询监控。
• 所有其他工具无需这些扩展即可工作。

最低要求

• PostgreSQL 12+（已在PostgreSQL 17上测试）
• Python 3.11
• 能够访问PostgreSQL服务器的网络连接
• 对系统目录的读取权限

所需的PostgreSQL配置

⚠️ 重要提示

一些MCP工具需要特定的PostgreSQL配置参数来收集统计信息。请选择以下配置方法之一：

💡 使用建议

受这些设置影响的工具：

• get_user_functions_stats：需要 track_functions = pl 或 track_functions = all。
• get_table_io_stats 和 get_index_io_stats：track_io_timing = on 可提供更准确的计时。
• get_database_stats：track_io_timing = on 可增强I/O计时。

⚠️ 重要提示

应用任何方法后，验证设置：

SELECT name, setting, context FROM pg_settings WHERE name IN ('track_activities', 'track_counts', 'track_io_timing', 'track_functions') ORDER BY name;

       name       | setting |  context  
------------------+---------+-----------
 track_activities | on      | superuser
 track_counts     | on      | superuser
 track_functions  | pl      | superuser
 track_io_timing  | on      | superuser
(4 rows)

方法1：postgresql.conf（适用于自管理的PostgreSQL，推荐）

在 postgresql.conf 中添加以下内容：

# 基本统计信息收集（通常默认启用）
track_activities = on
track_counts = on

# 函数统计工具所需
track_functions = pl    # 启用PL/pgSQL函数统计信息收集

# 可选但推荐用于准确的I/O计时
track_io_timing = on    # 启用I/O计时统计信息收集

然后重启PostgreSQL服务器。

方法2：PostgreSQL启动参数

对于Docker或命令行启动的PostgreSQL：

# Docker示例
docker run -d \
  -e POSTGRES_PASSWORD=mypassword \
  postgres:17 \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

# 直接使用postgres命令
postgres -D /data \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

方法3：动态配置（适用于AWS RDS、Azure、GCP等托管服务）

对于无法修改 postgresql.conf 的托管PostgreSQL服务，使用SQL命令动态更改设置：

-- 启用基本统计信息收集（通常默认启用）
ALTER SYSTEM SET track_activities = 'on';
ALTER SYSTEM SET track_counts = 'on';

-- 启用函数统计信息收集（需要超级用户权限）
ALTER SYSTEM SET track_functions = 'pl';

-- 启用I/O计时统计信息（可选但推荐）
ALTER SYSTEM SET track_io_timing = 'on';

-- 不重启重新加载配置（单独运行）
SELECT pg_reload_conf();

💡 使用建议

会话级测试的替代方法：

-- 仅为当前会话设置（临时）
SET track_activities = 'on';
SET track_counts = 'on';
SET track_functions = 'pl';
SET track_io_timing = 'on';

⚠️ 重要提示

使用命令行工具时，分别运行每个SQL语句，以避免事务块错误。

RDS/Aurora兼容性

• 此服务器为只读模式，可与RDS/Aurora上的普通角色配合使用。若要进行高级分析，请启用 pg_stat_statements；pg_stat_monitor 在托管引擎上不可用。
• 在RDS/Aurora上，建议使用数据库参数组而非 ALTER SYSTEM 进行持久设置。

-- 验证预加载设置
SHOW shared_preload_libraries;

-- 在目标数据库中启用扩展
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 推荐的监控可见性
GRANT pg_read_all_stats TO <app_user>;

示例查询

🟢 无需扩展的工具（始终可用）

• get_server_info
  • “显示PostgreSQL服务器版本和扩展状态。”
  • “检查是否安装了 pg_stat_statements。”
• get_active_connections
  • “显示所有活动连接。”
  • “列出当前会话的数据库和用户信息。”
• get_postgresql_config
  • “显示所有PostgreSQL配置参数。”
  • “查找所有与内存相关的配置设置。”
• get_database_list
  • “列出所有数据库及其大小。”
  • “显示带有所有者信息的数据库列表。”
• get_table_list
  • “列出 ecommerce 数据库中的所有表。”
  • “显示 public 模式下表的大小。”
• get_table_schema_info
  • “显示 ecommerce 数据库中 customers 表的详细模式信息。”
  • “获取 ecommerce 数据库中 products 表的列详细信息和约束。”
  • “分析 ecommerce 数据库 sales 模式中 orders 表的表结构，包括索引和外键。”
  • “显示 inventory 数据库 public 模式中所有表的模式概述。”
  • 📋 功能：列类型、约束、索引、外键、表元数据
  • ⚠️ 必需：必须指定 database_name 参数
• get_database_schema_info
  • “显示 ecommerce 数据库中所有模式及其内容。”
  • “获取 ecommerce 数据库中 sales 模式的详细信息。”
  • “分析 inventory 数据库的模式结构和权限。”
  • “显示 hr_system 数据库的模式概述，包括表计数和大小。”
  • 📋 功能：模式所有者、权限、对象计数、大小、内容
  • ⚠️ 必需：必须指定 database_name 参数
• get_table_relationships
  • “显示 ecommerce 数据库中 customers 表的所有关系。”
  • “分析 ecommerce 数据库 sales 模式中 orders 表的外键关系。”
  • “获取 ecommerce 数据库的全数据库关系概述。”
  • “查找 ecommerce 数据库中引用 products 表的所有表。”
  • “显示 inventory 数据库中的跨模式关系。”
  • 📋 功能：外键关系（入站/出站）、跨模式依赖关系、约束详细信息
  • ⚠️ 必需：必须指定 database_name 参数
  • 💡 使用方法：留空 table_name 可进行全数据库关系分析
• get_user_list
  • “列出所有数据库用户及其角色。”
  • “显示特定数据库的用户权限。”
• get_index_usage_stats
  • “分析索引使用效率。”
  • “查找当前数据库中未使用的索引。”
• get_database_size_info
  • “显示数据库容量分析。”
  • “查找按大小排序的最大数据库。”
• get_table_size_info
  • “显示表和索引大小分析。”
  • “查找特定模式中最大的表。”
• get_vacuum_analyze_stats
  • “显示最近的VACUUM和ANALYZE操作。”
  • “列出需要VACUUM的表。”
• get_current_database_info
  • “我当前连接到哪个数据库？”
  • “显示当前数据库信息和连接详细信息。”
  • “显示数据库编码、排序规则和大小信息。”
  • 📋 功能：数据库名称、编码、排序规则、大小、连接限制
  • 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
• get_table_bloat_analysis
  • “分析当前数据库中的表膨胀情况。”
  • “显示 ecommerce 数据库中死元组比率较高的表。”
  • “查找需要VACUUM维护的表。”
  • “检查死元组超过5000个的表的膨胀情况。”
  • 📋 功能：死元组比率、估计的膨胀大小、VACUUM建议
  • ⚠️ 必需：跨数据库分析时必须指定 database_name
• get_database_bloat_overview
  • “按模式显示全数据库的膨胀摘要。”
  • “获取 inventory 数据库的膨胀概述。”
  • “识别膨胀比率最高的模式。”
  • “根据膨胀统计信息进行数据库维护规划。”
  • 📋 功能：模式级聚合、维护优先级、大小建议
• get_autovacuum_status
  • “检查自动清理配置和触发条件。”
  • “显示需要立即进行自动清理的表。”
  • “分析 public 模式的自动清理阈值百分比。”
  • “查找接近自动清理触发点的表。”
  • 📋 功能：触发阈值分析、紧急程度分类、配置状态
  • 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
  • 💡 使用方法：使用 pg_stat_user_tables 进行无需扩展的自动清理监控
• get_autovacuum_activity
  • “显示过去48小时的自动清理活动模式。”
  • “监控自动清理执行频率和时间。”
  • “查找自动清理模式不规则的表。”
  • “分析最近的自动清理和自动分析历史。”
  • 📋 功能：活动模式、执行频率、时间分析
  • 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
  • 💡 使用方法：历史自动清理模式分析
• get_running_vacuum_operations
  • “显示当前正在运行的VACUUM和ANALYZE操作。”
  • “监控活动的维护操作及其进度。”
  • “检查是否有VACUUM操作阻塞查询。”
  • “查找长时间运行的维护操作。”
  • 📋 功能：实时操作状态、已用时间、影响级别、进程详细信息
  • 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
  • 💡 使用方法：使用 pg_stat_activity 进行实时维护监控
• get_vacuum_effectiveness_analysis
  • “分析VACUUM有效性和维护模式。”
  • “比较手动VACUUM和自动清理的效率。”
  • “查找维护模式不佳的表。”
  • “检查VACUUM频率与表活动比率。”
  • 📋 功能：维护模式分析、有效性评估、DML与VACUUM比率
  • 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
  • 💡 使用方法：使用现有统计信息进行战略性VACUUM分析
• get_table_bloat_analysis
  • “分析 public 模式中的表膨胀情况。”
  • “显示 ecommerce 数据库中死元组比率较高的表。”
  • “查找需要VACUUM维护的表。”
  • “检查死元组超过5000个的表的膨胀情况。”
  • 📋 功能：死元组比率、估计的膨胀大小、VACUUM建议
  • ⚠️ 必需：跨数据库分析时必须指定 database_name
• get_database_bloat_overview
  • “按模式显示全数据库的膨胀摘要。”
  • “获取 inventory 数据库的膨胀概述。”
  • “识别膨胀比率最高的模式。”
  • “根据膨胀统计信息进行数据库维护规划。”
  • 📋 功能：模式级聚合、维护优先级、大小建议
• get_lock_monitoring
  • “显示所有当前锁和阻塞的会话。”
  • “仅显示 granted = false 过滤后的阻塞会话。”
  • “使用用户名过滤器按特定用户监控锁。”
  • “使用模式过滤器检查排他锁。”
• get_wal_status
  • “显示WAL状态和归档信息。”
  • “监控WAL生成和当前LSN位置。”
• get_replication_status
  • “检查复制连接和延迟状态。”
  • “监控复制槽和WAL接收器状态。”
• get_database_stats
  • “显示全面的数据库性能指标。”
  • “分析事务提交比率和I/O统计信息。”
  • “监控缓冲区缓存命中率和临时文件使用情况。”
• get_bgwriter_stats
  • “分析检查点性能和时间。”
  • “显示检查点性能。”
  • “显示后台写入器效率统计信息。”
  • “监控缓冲区分配和fsync模式。”
• get_user_functions_stats
  • “分析用户定义函数的性能。”
  • “显示函数调用计数和执行时间。”
  • “识别自定义函数中的性能瓶颈。”
  • ⚠️ 需要：postgresql.conf 中 track_functions = pl
• get_table_io_stats
  • “分析表I/O性能和缓冲区命中率。”
  • “识别缓冲区缓存性能不佳的表。”
  • “监控TOAST表的I/O统计信息。”
  • 💡 增强功能：track_io_timing = on 可提供更准确的计时
• get_index_io_stats
  • “显示索引I/O性能和缓冲区效率。”
  • “识别导致过多磁盘I/O的索引。”
  • “监控索引缓存友好性模式。”
  • 💡 增强功能：track_io_timing = on 可提供更准确的计时
• get_database_conflicts_stats
  • “检查备用服务器上的复制冲突。”
  • “分析冲突类型和解决统计信息。”
  • “监控备用服务器查询取消模式。”
  • “监控WAL生成和当前LSN位置。”
• get_replication_status
  • “检查复制连接和延迟状态。”
  • “监控复制槽和WAL接收器状态。”

🚀 版本感知工具（自动适应）

• get_io_stats（新增！）
  • “显示全面的I/O统计信息。”（PostgreSQL 16+提供详细细分）
  • “分析I/O统计信息。”
  • “分析缓冲区缓存效率和I/O时间。”
  • “按后端类型和上下文监控I/O模式。”
  • 📈 PG16+：完整的 pg_stat_io 支持，包括计时、后端类型和上下文
  • 📊 PG12 - 15：基本的 pg_statio_* 回退，提供缓冲区命中率
• get_bgwriter_stats（增强！）
  • “显示后台写入器和检查点性能。”
  • 📈 PG15：单独的检查点器和后台写入器统计信息（独特功能）
  • 📊 PG12 - 14, 16+：合并的后台写入器统计信息（包括检查点器数据）
• get_server_info（增强！）
  • “显示服务器版本和兼容性功能。”
  • “检查服务器兼容性。”
  • “检查此PostgreSQL版本上可用的MCP工具。”
  • “显示功能可用性矩阵和升级建议。”
• get_all_tables_stats（增强！）
  • “显示所有表的全面统计信息。”（PG12 - 17版本兼容）
  • “使用 include_system = true 参数包括系统表。”
  • “分析表访问模式和维护需求。”
  • 📈 PG13+：跟踪自上次VACUUM以来的插入次数（n_ins_since_vacuum），以优化维护计划
  • 📊 PG12：兼容模式，不支持的列显示为NULL

🟡 需要扩展的工具

• get_pg_stat_statements_top_queries（需要 pg_stat_statements）
  • “显示前10个最慢的查询。”
  • “分析 inventory 数据库中的慢查询。”
  • 📈 版本兼容：PG12使用 total_time → total_exec_time 映射；PG13+使用原生列
  • 💡 跨版本：自动调整查询结构以兼容PostgreSQL 12 - 17
• get_pg_stat_monitor_recent_queries（可选，使用 pg_stat_monitor）
  • “实时显示最近的查询。”
  • “监控过去5分钟的查询活动。”
  • 📈 版本兼容：PG12使用 total_time → total_exec_time 映射；PG13+使用原生列
  • 💡 跨版本：自动调整查询结构以兼容PostgreSQL 12 - 17

💡 使用建议

所有工具都支持使用 database_name 参数进行多数据库操作。这允许PostgreSQL超级用户从单个MCP服务器实例分析和监控多个数据库。

工具兼容性矩阵

🟢 无需扩展的工具（始终可用）

🚀 版本感知工具（自动适应）

🟡 需要扩展的工具

⚠️ 重要提示

PostgreSQL 18支持：PostgreSQL 18目前处于测试阶段，Percona Distribution PostgreSQL尚未支持。待PostgreSQL 18达到稳定版本并提供发行版支持后，将添加相应支持。

故障排除

连接问题

1. 检查PostgreSQL服务器状态。
2. 验证 .env 文件中的连接参数。
3. 确保网络连接正常。
4. 检查用户权限。

扩展错误

1. 运行 get_server_info 检查扩展状态。
2. 安装缺失的扩展：

CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION pg_stat_monitor;

3. 如有需要，重启PostgreSQL。

配置问题

1. 函数统计信息显示 “未找到数据”：检查 track_functions 设置

SHOW track_functions;  -- 应为 'pl' 或 'all'

💡 使用建议

托管服务（如AWS RDS等）的快速修复方法：

ALTER SYSTEM SET track_functions = 'pl';
SELECT pg_reload_conf();

2. 缺少I/O计时数据：启用计时收集

SHOW track_io_timing;  -- 应为 'on'

💡 使用建议

快速修复方法：

ALTER SYSTEM SET track_io_timing = 'on';
SELECT pg_reload_conf();

3. 应用配置更改：

• 自管理：将设置添加到 postgresql.conf 并重启服务器。
• 托管服务：使用 ALTER SYSTEM SET + SELECT pg_reload_conf()。
• 临时测试：使用 SET parameter = value 为当前会话设置。
• 生成一些数据库活动以填充统计信息。

性能问题

1. 使用 limit 参数减少结果集大小。
2. 在非高峰时段运行监控。
3. 在运行分析之前检查数据库负载。

版本兼容性问题

⚠️ 重要提示

有关更多详细信息，请参阅 工具兼容性矩阵。

1. 首先运行兼容性检查：

# "使用 get_server_info 检查版本和可用功能"

2. 了解功能可用性：

• PostgreSQL 16 - 17：所有功能可用。
• PostgreSQL 15+：单独的检查点器统计信息。
• PostgreSQL 14+：并行查询跟踪。
• PostgreSQL 12 - 13：仅核心功能。

3. 如果工具显示 “不可用”：

• 该功能需要较新的PostgreSQL版本。
• 工具将自动使用最佳可用替代方案。
• 考虑升级PostgreSQL以获得增强的监控功能。

🔧 技术细节

测试与开发

# 使用MCP检查器进行测试
./scripts/run-mcp-inspector-local.sh

# 直接执行以进行调试
python -m src.mcp_postgresql_ops.mcp_main --log-level DEBUG

# 测试版本兼容性（需要不同的PostgreSQL版本）
# 修改.env中的POSTGRES_HOST以指向不同版本

# 运行测试（如果有）
uv run pytest

版本兼容性测试

MCP服务器可自动适应PostgreSQL 12 - 17版本。要跨版本进行测试：

1. 设置测试数据库：使用不同的PostgreSQL版本（12、14、15、16、17）。
2. 运行兼容性测试：指向每个版本并验证工具行为。
3. 检查功能检测：确保正确检测版本和功能可用性。
4. 验证回退行为：确认在较旧版本上的优雅降级。

安全说明

• 所有工具均为 只读 - 无数据修改功能。
• 输出中会屏蔽敏感信息（如密码）。
• 不直接执行SQL - 仅使用预定义查询。
• 遵循最小权限原则。

📄 许可证

本项目遵循 MIT许可证，您可以自由使用、修改和分发。

⭐ 其他项目

由同一作者开发的其他MCP服务器：

• MCP-Airflow-API
• MCP-Ambari-API
• LogSentinelAI - 基于LLB的日志分析器

🤝 贡献

我们始终欢迎新的贡献者！无论您是修复拼写错误、添加新的监控工具还是改进文档，每一份贡献都将使这个项目变得更好。

贡献方式：

• 🐛 报告问题或漏洞。
• 💡 提出新的PostgreSQL监控功能建议。
• 📝 改进文档。
• 🚀 提交拉取请求。
• ⭐ 如果您觉得这个项目有用，请给它加星！

💡 使用建议

代码库的设计非常便于添加新工具。请查看 mcp_main.py 中现有的 @mcp.tool() 函数。

MCPO Swagger文档

[MCPO Swagger URL] http://localhost:8003/postgresql-ops/docs