MCP Toolbox 的 postgres-list-database-stats 工具用一条 SQL 透视 PostgreSQL 全库性能【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本指南聚焦 MCP Toolbox for Databases 中 PostgreSQL 集成自带的postgres-list-database-stats工具系统讲解它的功能定位、六个输入参数、基于pg_stat_database的底层实现以及 JSON 响应中每个字段的统计含义。读完本文你将掌握如何在 MCP 客户端中直接调用该工具完成全实例数据库的缓存效率、事务吞吐、行级活动、临时文件与锁竞争等维度的体检并能通过仓库源码与集成测试理解其真实执行路径。工具概览数据库实例级别的性能体检报告postgres-list-database-stats是一个只读观测类工具它一次性列出实例内每个数据库的关键性能与活动统计覆盖五大维度缓存效率Cache Efficiency缓冲池命中率、从磁盘读取的块数、命中的块数事务吞吐Transaction Throughput提交/回滚事务数及回滚占比行级活动Row-level Activity查询返回行数、扫描抓取行数、插入/更新/删除行数临时文件使用Temporary File Usage临时文件个数与总字节数竞争与冲突Contention恢复冲突导致的查询取消数、死锁数、当前活跃连接数。它与同目录下的list_table_stats、list_query_stats等工具不同后两者关注单个表或单条查询而本工具以数据库database为粒度汇总整个实例适合在 MCP 客户端中作为实例级健康检查的起点先定位问题库再下钻到表或查询。从源码结构看该工具注册的资源类型常量即postgres-list-database-stats见 postgreslistdatabasestats.go工具声明为只读注解tools.NewReadOnlyAnnotations不会对数据库产生任何写入副作用Initialize。输入参数详解工具接收以下 6 个可选参数在 postgreslistdatabasestats.go 中定义参数类型默认值说明database_namestring按数据库名称做模糊匹配SQL 中为LIKE %...%传空则不限制include_templatesbooleanfalse设为true时结果中包含模板数据库如template0、template1database_ownerstring按数据库属主用户名模糊过滤default_tablespacestring按默认表空间名模糊过滤order_bystringdatabase_name升序仅接受size按数据库大小降序或commit按提交事务数降序两个值其余值回退到按名称排序limitinteger10返回的最大数据库条数要点说明database_name、database_owner、default_tablespace均为子串包含匹配而非精确匹配便于快速筛选SQL 侧通过LIKE % || $n || %实现。order_by只支持size与commit两种显式排序从实现看排序落在CASE WHEN $5::text size THEN database_size_bytes END DESC与CASE WHEN $5::text commit THEN xact_commit END DESC上其余情况下按database_name升序兜底。limit底层使用COALESCE($6::int, 10)即不传参时等价于 10若希望一次性拿到全部数据库可传入较大值。默认情况下工具会排除模板数据库且无论何种参数组合都会硬性排除 Cloud SQL 内部库cloudsqladmin见下文 SQL 的WHERE子句。在 MCP 配置中启用该工具postgres-list-database-stats已被纳入 PostgreSQL 预置配置prebuilt config只需通过--prebuiltpostgres启动服务即可使用无需手写任何 YAML{ mcpServers: { toolbox-postgres: { command: npx, args: [-y, toolbox-sdk/server, --prebuiltpostgres, --stdio] } } }如果你只想加载监控类工具可以使用 toolset 语法--prebuiltpostgres/monitor该 toolset 在 postgres.yaml 中明确包含list_database_stats与list_query_stats、list_active_queries、long_running_transactions、list_locks同组。预置配置依赖的环境变量使用预置配置时需要先通过环境变量配置连接信息参见 postgres.yaml 与 PostgreSQL 预置配置文档环境变量必填说明POSTGRES_HOST否PostgreSQL 服务器地址默认localhostPOSTGRES_PORT否端口默认5432POSTGRES_DATABASE是连接的目标数据库名POSTGRES_USER是数据库用户名POSTGRES_PASSWORD是用户密码POSTGRES_QUERY_PARAMS否追加到连接串上的原始查询参数权限方面连接用户需要对pg_stat_database、pg_database、pg_tablespace具备读取权限执行查询所需的最小数据库级SELECT权限才能完整返回各数据库统计。自定义配置方式不依赖预置配置时也可以用标准 YAML 声明工具。以下示例来自该工具的文档页完整继承了其 description 语义原文档示例kind: tool name: list_database_stats type: postgres-list-database-stats source: postgres-source description: | Lists the key performance and activity statistics for each PostgreSQL database in the instance, offering insights into cache efficiency, transaction throughput row-level activity, temporary file usage, and contention. It returns: the database name, whether the database is connectable, database owner, default tablespace name, the percentage of data blocks found in the buffer cache rather than being read from disk (a higher value indicates better cache performance), the total number of disk blocks read from disk, the total number of times disk blocks were found already in the cache; the total number of committed transactions, the total number of rolled back transactions, the percentage of rolled back transactions compared to the total number of completed transactions, the total number of rows returned by queries, the total number of live rows fetched by scans, the total number of rows inserted, the total number of rows updated, the total number of rows deleted, the number of temporary files created by queries, the total size of temporary files used by queries in bytes, the number of query cancellations due to conflicts with recovery, the number of deadlocks detected, the current number of active backend connections, the timestamp when the database statistics were last reset, and the total database size in bytes.其中type必须是postgres-list-database-statssource指向已定义的postgres类型数据源其连接池由pgxpool.Pool承载description可选缺省时工具会自动填充上述标准描述。字段完整说明见文档末尾的 Reference 表。说明该工具在 YAML 解析测试中验证了authRequired等扩展字段的兼容性postgreslistdatabasestats_test.go自定义配置时可按需补充annotations等元数据。底层实现基于 pg_stat_database 的聚合 SQL工具的核心是一条常驻源码的 SQLlistDatabaseStats 常量执行时由Invoke把参数展开后调用数据源的RunSQL交给连接池执行Invoke并未经过任何应用层加工——你看到的 JSON 字段与 SQL 列一一对应。它一次 JOIN 了三张系统视图/表pg_stat_database统计源别名为s提供各数据库的缓存、事务、元组、临时文件、冲突/死锁、活跃连接等累计统计pg_databased提供datallowconn是否允许连接、属主datdba、datistemplate是否模板库等元数据并通过d.oid s.datid关联pg_tablespacets提供默认表空间名通过ts.oid d.dattablespace关联。几个值得注意的实现细节缓存命中率CASE WHEN (s.blks_hit s.blks_read) 0 THEN 0 ELSE round((s.blks_hit * 100.0) / (s.blks_hit s.blks_read), 2) END——当缓冲池没有产生任何读写块时分母为 0工具显式返回 0 而非报错。回滚占比round(s.xact_rollback * 100.0 / (s.xact_commit s.xact_rollback 1), 2)——分母额外1防止除零同时保留两位小数。数据来源限定WHERE子句永久排除cloudsqladmin内部库适配 Cloud SQL 环境并通过AND ($2::boolean IS TRUE OR d.datistemplate IS FALSE)实现模板库的可选开关。模糊过滤($1::text IS NULL OR database_name LIKE % || $1::text || %)等三组条件分别作用于库名、属主、表空间传空字符串时参数值并非 NULL因此会按LIKE %%匹配全部与文档所述默认不限制一致。排序兜底仅当$5等于size或commit时启用对应降序排列否则始终按database_name升序。限制LIMIT COALESCE($6::int, 10)保证未传limit时最多返回 10 条。响应字段说明工具返回一个 JSON 数组每个元素代表一个数据库。字段与 SQL 列一一对应原文档响应示例{ database_name: Name of the database, is_connectable: Boolean indicating Whether the database allows connections, database_owner: Username of the database owner, default_tablespace: Name of the default tablespace for the database, cache_hit_ratio_percent: The percentage of data blocks found in the buffer cache rather than being read from disk, blocks_read_from_disk: The total number of disk blocks read for this database, blocks_hit_in_cache: The total number of times disk blocks were found already in the cache., xact_commit: The total number of committed transactions, xact_rollback: The total number of rolled back transactions, rollback_ratio_percent: The percentage of rolled back transactions compared to the total number of completed transactions, rows_returned_by_queries: The total number of rows returned by queries, rows_fetched_by_scans: The total number of live rows fetched by scans, tup_inserted: The total number of rows inserted, tup_updated: The total number of rows updated, tup_deleted: The total number of rows deleted, temp_files: The number of temporary files created by queries, temp_size_bytes: The total size of temporary files used by queries in bytes, conflicts: Number of query cancellations due to conflicts, deadlocks: Number of deadlocks detected, active_connections: The current number of active backend connections, statistics_last_reset: The timestamp when the database statistics were last reset, database_size_bytes: The total disk size of the database in bytes }各字段分组解读标识与元数据database_name、is_connectable源自pg_database.datallowconn、database_ownerpg_get_userbyid(d.datdba)解析出的用户名、default_tablespace。缓存性能cache_hit_ratio_percent越高说明越多的数据块命中缓冲池而无需访问磁盘配合blocks_read_from_diskblks_read与blocks_hit_in_cacheblks_hit可判断是否需要调大shared_buffers或优化访问模式。事务吞吐xact_commit与xact_rollback来自pg_stat_databaserollback_ratio_percent是工具额外计算的百分比回滚占比异常升高通常是应用层错误重试或约束冲突的信号。行级活动rows_returned_by_queriestup_returned、rows_fetched_by_scanstup_fetched以及tup_inserted/tup_updated/tup_deleted反映读写负载分布。临时文件temp_files与temp_size_bytestemp_bytes对应排序/哈希溢出到磁盘的量级可用于判断work_mem是否偏小。竞争与冲突conflicts表示与恢复过程冲突被取消的查询次数主从环境常见deadlocks为检测到的死锁数active_connectionsnumbackends为当前活跃后端连接数。其他statistics_last_resetstats_reset为统计重置时间戳database_size_bytes来自pg_database_size(s.datid)即数据库当前占用磁盘的字节数。注意这些累计统计除active_connections、database_size_bytes外均为自统计重置以来的累积值适合观察趋势与比例而非瞬时状态。兼容的数据源该工具定义了一个compatibleSource接口要求数据源提供PostgresPool()与RunSQL接口定义因此不仅适用于原生 PostgreSQL也适用于基于 PostgreSQL 协议的托管服务。在 文档头部 标注的兼容来源包括AlloyDB for PostgreSQL见 AlloyDB PostgreSQL 集成预置配置 alloydb-postgres.yamlCloud SQL for PostgreSQL见 Cloud SQL for PostgreSQL 集成预置配置 cloud-sql-postgres.yaml此外 AlloyDB Omni 的预置配置 alloydb-omni.yaml 也注册了该工具。三者的集成测试均实际调用了RunPostgresListDatabaseStatsTestalloydb 集成测试、alloydbpg 集成测试、cloudsqlpg 集成测试说明该工具在三种环境下的行为一致。集成测试如何验证该工具仓库在 tests/tool.go 中提供了完整的集成测试RunPostgresListDatabaseStatsTest其验证思路可以直接复用为手工验收步骤准备数据动态创建两个随机命名的数据库及对应属主角色setUpDatabase避免与既有数据冲突调用 API向POST http://127.0.0.1:5000/api/tool/list_database_stats/invoke发送请求体覆盖四种场景按database_name过滤期望只返回该库按database_owner过滤期望返回属主匹配的库组合default_tablespace如pg_default与库名过滤按sort_bysize排序。断言仅比较database_name、database_owner、default_tablespace、is_connectable四个稳定字段忽略每次运行都会变化的统计值并忽略不相关的既有数据库。这段测试从行为上印证了三个事实过滤参数按库名/属主/表空间生效、default_tablespace对默认库通常为pg_default、返回体为 JSON 数组。典型使用场景与最佳实践结合工具能力与上述实现推荐以下用法实例级巡检不带任何参数调用获取默认 10 个数据库的概况先看cache_hit_ratio_percent是否普遍偏低如 95% 需要关注缓存配置再看rollback_ratio_percent与deadlocks是否异常。定位热点库设置order_bysize快速找到体积最大的库配合order_bycommit找到写入最繁忙的库作为容量规划与迁移评估的依据。多条件组合筛选用database_owner找到某业务团队名下的库或用default_tablespace定位存放在慢速/独立表空间上的库。观察趋势对比不同时间点的temp_files/temp_size_bytes或rows_fetched_by_scans结合statistics_last_reset判断统计窗口辅助诊断排序溢出或扫描型查询问题。作为监控 toolset 的一部分--prebuiltpostgres/monitor将它与查询统计、活跃查询、长事务、锁检测工具组合构成完整的实例监控闭环。小结postgres-list-database-stats以一条 JOIN 三张系统视图的聚合 SQL 为内核通过 MCP Toolbox 将 PostgreSQL 的pg_stat_database统计以结构化 JSON 暴露给 Agent覆盖缓存、事务、元组、临时文件与锁竞争五个维度六个可选参数提供了按库名/属主/表空间过滤、按大小或提交数排序、控制返回条数与模板库开关的灵活查询能力。它同时兼容 PostgreSQL、Cloud SQL for PostgreSQL 与 AlloyDB含 Omni并配有覆盖多种过滤与排序场景的集成测试是实例级数据库健康检查中低成本、高信息密度的首选入口。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考