Postgres MCP

概述

Postgres Pro是一个开源模型上下文协议 (MCP) 服务器，旨在为您和您的 AI 代理在整个开发过程中提供支持——从初始编码、测试和部署，到生产调整和维护。

Postgres Pro 所做的远不止包装数据库连接。

功能包括：

有关我们构建 Postgres Pro 的原因的更多背景信息，请参阅我们的发布博客文章。

演示

从无法使用到闪电般快速

**挑战：**我们使用 AI 助手生成了一个电影应用程序，但 SQLAlchemy ORM 代码运行速度非常慢
**解决方案：**使用 Postgres Pro 和 Cursor，我们在几分钟内解决了性能问题

我们使用 Cursor AI 代理和 Postgres Pro 来：

🚀 修复性能 - 包括 ORM 查询、索引和缓存
🛠️ 修复需要将数据连接到代码的错误
🧠 从单个提示添加新功能

观看下面的视频或阅读详细内容。

https://github.com/user-attachments/assets/24e05745-65e9-4998-b877-a368f1eadc13

快速入门

先决条件

在开始之前，请确保您已：

访问数据库的凭据。
Docker或Python 3.12 或更高版本。

访问凭证

您可以使用psql或 GUI 工具（例如pgAdmin ）来确认您的访问凭据是否有效。

Docker 或 Python

使用 Docker 还是 Python，完全由您决定。我们通常推荐 Docker，因为 Python 用户可能会遇到更多特定于环境的问题。不过，使用您最熟悉的方法通常更明智。

安装

选择以下方法之一来安装 Postgres Pro：

选项 1：使用 Docker

拉取 Postgres Pro MCP 服务器 Docker 镜像。此镜像包含所有必要的依赖项，可在各种环境中可靠地运行 Postgres Pro。

docker pull crystaldba/postgres-mcp

选项 2：使用 Python

如果您已经安装了pipx ，则可以使用以下命令安装 Postgres Pro：

pipx install postgres-mcp

否则，使用uv安装 Postgres Pro：

uv pip install postgres-mcp

如果需要安装uv ，请参阅uv 安装说明。

配置你的AI助手

我们提供了使用 Claude Desktop 配置 Postgres Pro 的完整说明。许多 MCP 客户端都有类似的配置文件，您可以根据您选择的客户端调整这些步骤。

Claude桌面配置

您需要编辑 Claude Desktop 配置文件来添加 Postgres Pro。此文件的位置取决于您的操作系统：

MacOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%/Claude/claude_desktop_config.json

您还可以使用 Claude Desktop 中的Settings菜单项来定位配置文件。

现在您将编辑配置文件的mcpServers部分。

如果你正在使用 Docker

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

Postgres Pro Docker 镜像将自动重新映射主机名localhost以便在容器内部工作。

MacOS/Windows：自动使用host.docker.internal
Linux：自动使用172.17.0.1或适当的主机地址

如果你使用`pipx`

{
  "mcpServers": {
    "postgres": {
      "command": "postgres-mcp",
      "args": [
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

如果你使用`uv`

{
  "mcpServers": {
    "postgres": {
      "command": "uv",
      "args": [
        "run",
        "postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

连接 URI

将postgresql://...替换为您的Postgres 数据库连接 URI 。

访问模式

Postgres Pro 支持多种访问模式，让您可以控制 AI 代理可以在数据库上执行的操作：

不受限制模式：允许完全读/写访问权限以修改数据和架构。适用于开发环境。
限制模式：将操作限制为只读事务，并对资源利用率施加限制（目前仅限制执行时间）。适用于生产环境。

要使用受限模式，请将上面的配置示例中的--access-mode=unrestricted替换为--access-mode=restricted 。

其他 MCP 客户端

许多 MCP 客户端具有与 Claude Desktop 类似的配置文件，您可以调整上述示例以适合您选择的客户端。

如果您正在使用 Cursor，您可以从Command Palette导航到Cursor Settings ，然后打开MCP选项卡来访问配置文件。
如果您正在使用 Windsurf，您可以从Command Palette导航到Open Windsurf Settings Page来访问配置文件。
如果您使用 Goose 运行goose configure ，然后选择Add Extension 。

Postgres 扩展安装（可选）

要启用索引调整和综合性能分析，您需要在数据库上加载pg_statements和hypopg扩展。

pg_statements扩展允许 Postgres Pro 分析查询执行统计数据。例如，这可以帮助它了解哪些查询运行缓慢或消耗大量资源。
hypopg扩展允许 Postgres Pro 在添加索引后模拟 Postgres 查询规划器的行为。

在 AWS RDS、Azure SQL 或 Google Cloud SQL 上安装扩展

如果您的 Postgres 数据库在云提供商托管服务上运行，则pg_statements和hypopg扩展应该已在系统上可用。在这种情况下，您只需使用具有足够权限的角色运行CREATE EXTENSION命令即可：

CREATE EXTENSION IF NOT EXISTS pg_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;

在自管理 Postgres 上安装扩展

如果您正在管理自己的 Postgres 安装，则可能需要进行一些额外的工作。在加载pg_statements扩展之前，您必须确保它已列在 Postgres 配置文件的shared_preload_libraries中。hypopg hypopg可能还需要额外的系统级安装（例如，通过您的包管理器），因为它并非始终随 Postgres 提供。

使用示例

获取数据库健康概览

问：

检查我的数据库的健康状况并找出任何问题。

分析慢查询

问：

我的数据库中最慢的查询是什么？如何才能加快它们的速度？

获取有关如何加快速度的建议

问：

我的应用运行缓慢。如何让它运行得更快？

生成索引建议

问：

分析我的数据库工作负载并建议索引以提高性能。

优化特定查询

问：

帮我优化这个查询：SELECT * FROM orders JOIN customers ON orders.customer_id = customer.id WHERE orders.created_at > '2023-01-01';

MCP 服务器 API

MCP 标准定义了各种类型的端点：工具、资源、提示等。

Postgres Pro 仅通过MCP 工具提供功能。我们之所以选择这种方式，是因为MCP 客户端生态系统对 MCP 工具提供了广泛的支持。这与其他 Postgres MCP 服务器（包括参考 Postgres MCP 服务器）的做法形成了鲜明对比，这些服务器使用MCP 资源来公开架构信息。

Postgres Pro工具：

工具名称	描述
`list_schemas`	列出 PostgreSQL 实例中可用的所有数据库模式。
`list_objects`	列出指定模式内的数据库对象（表、视图、序列、扩展）。
`get_object_details`	提供有关特定数据库对象的信息，例如表的列、约束和索引。
`execute_sql`	在数据库上执行 SQL 语句，在受限模式下连接时具有只读限制。
`explain_query`	获取 SQL 查询的执行计划，描述 PostgreSQL 将如何处理该查询，并公开查询规划器的开销模型。可以使用假设索引来调用它，以模拟添加索引后的行为。
`get_top_queries`	使用`pg_stat_statements`数据根据总执行时间报告最慢的 SQL 查询。
`analyze_workload_indexes`	分析数据库工作负载以识别资源密集型查询，然后为其推荐最佳索引。
`analyze_query_indexes`	分析特定 SQL 查询列表（最多 10 个）并为它们推荐最佳索引。
`analyze_db_health`	执行全面的健康检查，包括：缓冲区缓存命中率、连接健康、约束验证、索引健康（重复/未使用/无效）、序列限制和真空健康。

常见问题

*Postgres Pro 与其他 Postgres MCP 服务器有何不同？*许多 MCP 服务器允许 AI 代理针对 Postgres 数据库运行查询。Postgres Pro 不仅支持此功能，还添加了用于理解和改进 Postgres 数据库性能的工具。例如，它实现了适用于 Microsoft SQL Server 的数据库调优顾问的 Anytime 算法版本，这是一种用于自动索引调优的现代工业级算法。

Postgres Pro	其他 Postgres MCP 服务器
✅ 确定性数据库健康检查	❌ 不可重复的 LLM 生成的健康查询
✅ 原则性索引搜索策略	❌ Gen-AI 猜测索引改进
✅ 工作负载分析，找出主要问题	❌ 问题分析不一致
✅ 模拟性能改进	❌ 亲自尝试一下，看看是否有效

Postgres Pro 通过添加确定性工具和经典优化算法来补充生成式人工智能，这种组合既可靠又灵活。

既然 LLM 可以推理、生成 SQL 等，为什么还需要 MCP 工具呢？ LLM 对于涉及歧义、推理或自然语言的任务非常有用。然而，与过程式代码相比，它们可能速度慢、成本高、不确定，有时还会产生不可靠的结果。在数据库调优方面，我们拥有经过数十年开发、久经考验的成熟算法。Postgres Pro 通过将 LLM 与经典优化算法和其他过程式工具结合使用，让您能够兼顾两者的优势。

*如何测试 Postgres Pro？*测试对于确保 Postgres Pro 的可靠性和准确性至关重要。我们正在构建一套由 AI 生成的对抗性工作负载，旨在挑战 Postgres Pro，并确保其在各种场景下都能出色地运行。

*支持哪些 Postgres 版本？*我们目前的测试重点是 Postgres 15、16 和 17。我们计划支持 Postgres 13 到 17 版本。

*谁创建了这个项目？*该项目由Crystal DBA创建并维护。

路线图

待定

您和您的需求是我们构建产品的关键驱动力。请通过提交问题或拉取请求告诉我们您希望看到的内容。您也可以通过Discord联系我们。

技术说明

本节包括影响 Postgres Pro 设计的高级概述技术考虑。

索引调整

开发人员都知道，缺少索引是导致数据库性能问题的最常见原因之一。索引提供的访问方法使 Postgres 能够快速定位执行查询所需的数据。当表较小时，索引的作用不大，但随着数据量的增长，表扫描和索引查找之间的算法复杂度差异变得显著（通常为O ( n ) vs O ( logn )，如果涉及多个表的连接*，*则可能更大）。

在 Postgres Pro 中生成建议索引分为几个阶段进行：

识别需要调优的 SQL 查询。如果您知道某个特定的 SQL 查询存在问题，您可以提供该问题。Postgres Pro 还可以分析工作负载以确定索引调优目标。为此，它依赖于pg_stat_statements扩展，该扩展记录每个查询的运行时和资源消耗。如果查询是资源消耗最大的查询（无论是按每次执行还是按总体计算），则该查询可以作为索引调优的候选。目前，我们使用执行时间作为累积资源消耗的指标，但查看具体资源（例如访问的块数或从磁盘读取的块数）也可能有意义。analyze_query_workload 工具专注于慢速查询，使用每次执行的平均时间，并设置执行次数和平均执行时间get_top_queries``analyze_query_workload它接受一个表示平均执行时间与总执行时间的参数，然后将这些查询传递给analyze_query_indexes以获取索引建议。复杂的索引调优系统使用“工作负载压缩”来生成一个具有代表性的查询子集，该子集能够反映整体工作负载的特征，从而减少下游算法的计算量。Postgres Pro 通过规范化查询来执行有限形式的工作负载压缩，使来自同一模板的查询看起来像一个查询。它对每个查询赋予相同的权重，这种简化方法在索引效益显著时非常有效。
生成候选索引一旦我们有了想要通过索引改进的 SQL 查询列表，我们就会生成一个可能想要添加的索引列表。为此，我们需要解析 SQL 查询，并识别出在筛选、连接、分组或排序中使用的所有列。为了生成所有可能的索引，我们需要考虑这些列的组合，因为 Postgres 支持多列索引。在当前的实现中，我们只包含每个可能的多列索引的一个排列，并且是随机选择的。我们进行这种简化是为了缩小搜索空间，因为排列通常具有同等的性能。然而，我们希望在这方面有所改进。
寻找最佳索引配置。我们的目标是找到在性能优势与存储和维护这些索引的成本之间实现最佳平衡的索引组合。我们使用hypopg扩展提供的“假设分析”功能来估算性能提升。该扩展模拟了 Postgres 查询优化器在添加索引后执行查询的方式，并根据实际的 Postgres 成本模型报告变化。一个挑战是，生成查询计划通常需要了解查询中使用的具体参数值。查询规范化对于减少查询数量至关重要，它会删除参数常量。同样，我们也无法获取通过绑定变量提供的参数值。为了解决这个问题，我们通过从表统计信息中抽样，生成了一些可以作为参数的实际常量。在 Postgres 16 版本中，它添加了通用的解释计划功能，但它存在一些限制，例如LIKE子句，而我们的实现没有这些限制。搜索策略至关重要，因为评估所有可能的索引组合仅在简单情况下可行。这正是各种索引方法之间的主要区别所在。我们借鉴微软 Anytime 算法，采用贪婪搜索策略，即先找到最佳的单索引解决方案，然后再找到最佳的索引添加到该解决方案中，从而得到双索引解决方案。当时间预算耗尽或一轮探索未能产生超过 10% 最低改进阈值的任何收益时，我们的搜索终止。
成本效益分析。当面临两种索引方案时，一种性能更佳，另一种则需要更多空间，我们该如何选择？传统上，索引顾问会询问存储预算，并根据该预算优化性能。我们也会考虑存储预算，但会在整个优化过程中进行成本效益分析。我们将此问题定义为在帕累托前沿上选择一个点的问题——帕累托前沿是一组选择，对于这些选择，改善一个质量指标必然会导致另一个指标恶化。在理想情况下，我们可能希望以金钱形式评估存储成本和性能提升带来的好处。然而，有一种更简单、更实用的方法：从相对角度来看待变化。大多数人会同意，即使存储成本是 2 倍，100 倍的性能提升也是值得的。在我们的实现中，我们使用一个可配置参数来设置此阈值。默认情况下，我们要求性能提升的对数（以 10 为底）的变化量是空间成本对数差异的 2 倍。这意味着，性能提升 100 倍时，最多可以将空间增加 10 倍。

我们的实现与 Microsoft SQL Server 中的Anytime 算法最为接近。与 Postgres 的自动索引工具Dexter相比，我们的搜索范围更大，并使用了不同的启发式算法。这使我们能够以更长的运行时间为代价来生成更好的解决方案。

我们还展示了每轮搜索中完成的工作，包括添加每个索引前后查询计划的比较。这为 LLM 提供了额外的上下文，使其能够在响应索引建议时使用。

数据库健康

数据库健康检查能够在导致严重问题之前识别出调整机会和维护需求。在当前版本中，Postgres Pro 直接从PgHero调整了数据库健康检查。我们正在努力全面验证这些检查，并可能在未来进行扩展。

索引健康。查找未使用的索引、重复的索引以及臃肿的索引。臃肿的索引会导致数据库页面利用率低下。Postgres 自动清理会清理指向死元组的索引条目，并将这些条目标记为可重用。但是，它不会压缩索引页，最终导致索引页中可能只包含少量活跃的元组引用。
缓冲区缓存命中率。衡量从缓冲区缓存而非磁盘读取数据库的比例。必须调查较低的缓冲区缓存命中率，因为它通常不是成本最优的，并且会导致应用程序性能下降。
连接健康。检查数据库连接数并报告其使用情况。最大的风险是连接耗尽，但大量空闲或阻塞的连接也可能表明存在问题。
真空健康。真空之所以重要，原因有很多。其中一个关键点是防止事务 ID 回绕，这可能导致数据库停止接受写入操作。Postgres 多版本并发控制 (MVCC) 机制要求每个事务都有一个唯一的事务 ID。但是，由于 Postgres 使用 32 位有符号整数作为事务 ID，因此它需要在最多 20 亿个事务之后重用事务 ID。为此，它会“冻结”历史事务的事务 ID，将它们全部设置为表示遥远过去的特殊值。当记录首次写入磁盘时，它们会被写入一系列事务 ID 的可见性。在重新使用这些事务 ID 之前，Postgres 必须更新所有磁盘记录，将其“冻结”以删除对要重用的事务 ID 的引用。此检查会查找需要真空处理的表，以防止事务 ID 回绕。
复制健康。通过监控主服务器和副本之间的滞后、验证复制状态以及跟踪复制槽的使用情况来检查复制健康状况。
约束健康。在正常运行期间，Postgres 会拒绝任何可能导致约束违规的事务。但是，在加载数据后或在恢复场景中可能会出现无效约束。此检查会查找任何无效约束。
序列健康。查找有可能超过其最大值的序列。

Postgres 客户端库

Postgres Pro 使用psycopg3通过异步 I/O 连接到 Postgres。在底层，psycopg3 使用libpq库连接到 Postgres，从而提供对 Postgres 完整功能集的访问，以及由 Postgres 社区全面支持的底层实现。

其他一些基于 Python 的 MCP 服务器使用asyncpg ，它可以通过消除libpq依赖来简化安装。asyncpg 可能也比 psycopg3更快，但我们尚未亲自验证这一点。较旧的基准测试报告显示性能差距较大，这表明较新的 psycopg3 随着其成熟已经缩小了差距。

综合考虑这些因素，我们最终选择了psycopg3 ，而不是asyncpg 。我们愿意在未来重新考虑这一决定。

连接配置

与参考 PostgreSQL MCP 服务器一样，Postgres Pro 在启动时会获取 Postgres 连接信息。这对于始终连接到同一数据库的用户来说非常方便，但在切换数据库时可能会比较麻烦。

PG-MCP采取的另一种方法是，在使用时通过 MCP 工具调用提供连接详细信息。这对于切换数据库的用户来说更加方便，并且允许单个 MCP 服务器同时支持多个最终用户。

肯定有比这两种方法更好的方法。这两种方法都存在安全漏洞——很少有 MCP 客户端能够安全地存储 MCP 服务器配置（Goose 是个例外），而且通过 MCP 工具提供的凭证会通过 LLM 传递并存储在聊天历史记录中。在某些情况下，这两种方法也存在可用性问题。

架构信息

模式信息工具的目的是为调用的 AI 代理提供生成正确且高性能 SQL 所需的信息。例如，假设用户询问：“过去一年有多少航班从旧金山起飞并降落在巴黎？” AI 代理需要找到存储航班的表、存储出发地和目的地的列，以及可能还有一张映射机场代码和机场位置的表。

当 LLM 通常能够生成 SQL 以直接从 Postgres 检索此信息时，为什么还要提供模式信息工具？

我们使用 Claude 的经验表明，调用 Claude 的 LLM 非常擅长通过查询Postgres 系统目录和信息模式（ANSI 标准化的数据库元数据视图）来生成 SQL 语句，从而探索 Postgres 模式。然而，我们不确定其他 LLM 是否也能如此可靠且高效地完成这项工作。

使用MCP 资源而不是MCP 工具来提供模式信息是否更好？

参考 PostgreSQL MCP 服务器使用资源（而非工具）来公开架构信息。资源导航类似于文件系统导航，因此这种方法在很多方面都很自然。然而，在 MCP 客户端生态系统中，资源支持不如工具支持广泛（参见示例客户端）。此外，虽然 MCP 标准规定资源可以由 AI 代理或最终用户访问，但某些客户端仅支持人工导航资源树。

受保护的 SQL 执行

人工智能加剧了长期以来保护数据库免受各种威胁（从简单的错误到恶意行为者的复杂攻击）的挑战。无论威胁是意外的还是恶意的，都适用类似的安全框架，其目标分为三类：机密性、完整性和可用性。便捷性和安全性之间常见的矛盾也显而易见。

Postgres Pro 受保护的 SQL 执行模式注重完整性。在 MCP 环境中，我们最担心的是 LLM 生成的 SQL 会造成损害——例如，意外的数据修改或删除，或其他可能规避组织变更管理流程的更改。

确保完整性最简单的方法是确保所有针对数据库执行的 SQL 都是只读的。一种方法是创建一个具有只读访问权限的数据库用户。虽然这是一个很好的方法，但在实践中很多人觉得这很麻烦。Postgres 不提供将连接或会话置于只读模式的方法，因此 Postgres Pro 使用一种更复杂的方法来确保在读写连接上执行只读 SQL。

Postgres 提供只读事务模式，可防止数据和架构被修改。与参考 PostgreSQL MCP 服务器一样，我们使用只读事务来提供受保护的 SQL 执行。

为了使该机制健壮，我们需要确保 SQL 不会以某种方式规避只读事务模式，比如通过发出COMMIT或ROLLBACK语句然后开始新的事务。

例如，LLM 可以通过发出ROLLBACK语句并开始新事务来规避只读事务模式。例如：

ROLLBACK; DROP TABLE users;

为了防止此类情况发生，我们会在执行 SQL 语句之前使用pglast库对其进行解析。我们会拒绝任何包含commit或rollback语句的 SQL 语句。值得一提的是，主流的 Postgres 存储过程语言（包括 PL/pgSQL 和 PL/Python）都不允许使用COMMIT或ROLLBACK语句。如果您的数据库启用了不安全的存储过程语言，那么我们的只读保护机制可能会被绕过。

目前，Postgres Pro 为数据库提供了两种级别的保护，分别处于便利性/安全性的极端。

“无限制”模式提供了最大的灵活性。它适用于速度和灵活性至关重要，且无需保护宝贵或敏感数据的开发环境。
“受限”在灵活性和安全性之间取得了平衡。它适用于数据库暴露给不受信任的用户的生产环境，以及保护有价值或敏感数据非常重要的环境。

不受限制模式与Cursor 自动运行模式的方法一致，在该模式下，AI 代理在有限的人工监督或批准下运行。我们期望自动运行模式部署在以下开发环境中：错误后果较轻，数据库不包含有价值或敏感的数据，并且可以在需要时重新创建或从备份中恢复。

我们设计受限模式时秉持着保守的原则，宁可牺牲安全性，即使它可能带来不便。受限模式仅限于只读操作，并且我们限制查询执行时间，以防止长时间运行的查询影响系统性能。未来我们可能会添加其他措施，以确保受限模式在生产数据库中能够安全使用。

Postgres Pro 开发

以下说明适用于想要使用 Postgres Pro 的开发人员，或喜欢从源代码安装 Postgres Pro 的用户。

本地开发设置

安装 uv ：
curl -sSL https://astral.sh/uv/install.sh | sh
克隆存储库：
git clone https://github.com/crystaldba/postgres-mcp.git cd postgres-mcp
安装依赖项：
uv pip install -e . uv sync
运行服务器：
uv run postgres-mcp "postgres://user:password@localhost:5432/dbname"

Integrations

概述

演示