dbhub

DBHub 数据库查询指南

通过 DBHub 的 MCP 服务处理数据库时，始终遵循先探索，后查询的模式。不了解架构就直接编写 SQL，是最常见的错误——这会导致查询失败、浪费令牌，并让用户感到沮丧。

可用工具

DBHub 默认提供两个 MCP 工具，此外还提供可选工具：

工具	用途
search_objects	探索数据库结构——架构、表、列、索引、存储过程、函数
execute_sql	对数据库执行 SQL 语句
explain_sql（可选）	显示查询的执行计划，但不运行查询——仅当源配置启用此功能时才会提供
health_check（可选）	报告连接池状态和缓冲区缓存命中率——仅当源配置启用此功能时才会提供；仅适用于 PostgreSQL、MySQL、MariaDB、SQL Server 和 Oracle

如果配置了多个数据库，DBHub 会为每个数据源注册单独的工具（例如，search_objects_prod_pg、execute_sql_staging_mysql）。调用名称对应的工具即可选择所需数据库。

如果 explain_sql 可用（请查看工具列表），优先使用它，而不要猜测查询是否高效——即使面对启用了写入权限或只读的数据源，也可以安全调用，因为它不会执行语句。

如果 health_check 可用，并且查询似乎很慢或连接似乎已耗尽，请先调用它再推测原因——它会报告实时连接池和缓存命中数据，而不是让你猜测原因。

先探索，后查询的工作流

每项数据库任务都应遵循以下步骤。关键在于，每一步都会缩小范围，这样你就不会浪费令牌加载不需要的信息。

第 1 步：了解有哪些架构

search_objects(object_type="schema", detail_level="names")

这能让你了解整体情况。大多数数据库都有一个主架构（例如，PostgreSQL 中的 public、SQL Server 中的 dbo），以及可以忽略的系统架构。

第 2 步：查找相关表

了解架构后，列出其中的表：

search_objects(object_type="table", schema="public", detail_level="names")

如果要查找特定内容，请使用匹配模式：

search_objects(object_type="table", schema="public", pattern="%user%", detail_level="names")

pattern 参数使用 SQL LIKE 语法：% 匹配任意字符，_ 匹配单个字符。

如果需要更多上下文来识别正确的表（行数、列数、表注释），请改用 detail_level="summary"。

第 3 步：检查表结构

编写任何查询前，先了解各列：

search_objects(object_type="column", schema="public", table="users", detail_level="full")

这会返回列名、数据类型、是否可为空以及默认值——这些信息足以帮助你编写正确的 SQL。

要了解查询性能或联接模式，还要检查索引：

search_objects(object_type="index", schema="public", table="users", detail_level="full")

第 4 步：编写并执行查询

现在你已了解准确的表名和列名，可以编写精确的 SQL：

execute_sql(sql="SELECT id, email, created_at FROM public.users WHERE created_at > '2024-01-01' ORDER BY created_at DESC")

渐进式披露：选择合适的详细程度

detail_level 参数决定 search_objects 返回多少信息。先从最少信息开始，只在需要时逐步深入——这样可以加快响应速度并提高令牌使用效率。

级别	返回内容	适用场景
names	仅对象名称	浏览、查找合适的表
summary	名称 + 元数据（行数、列数、注释）	在相似表之间进行选择、了解数据量
full	完整结构（包含类型的列、索引、存储过程定义）	编写查询前、了解关系

经验法则： 使用 names 进行广泛探索，使用 summary 缩小范围，仅对要查询的具体表使用 full。

使用多个数据库

为 DBHub 配置多个数据库源时，它会为每个数据源注册单独的工具实例。工具名称遵循 {tool}_{source_id} 模式：

# Query the production PostgreSQL database
search_objects_prod_pg(object_type="table", schema="public", detail_level="names")
execute_sql_prod_pg(sql="SELECT count(*) FROM orders")

# Query the staging MySQL database
search_objects_staging_mysql(object_type="table", detail_level="names")
execute_sql_staging_mysql(sql="SELECT count(*) FROM orders")

在单数据库配置中，工具名称就是 search_objects 和 execute_sql，不带任何后缀。用户提到特定数据库或环境时，请调用名称对应的工具。

搜索特定对象

search_objects 工具支持在所有对象类型中进行定向搜索：

# Find all tables with "order" in the name
search_objects(object_type="table", pattern="%order%", detail_level="names")

# Find columns named "email" across all tables
search_objects(object_type="column", pattern="email", detail_level="names")

# Find stored procedures matching a pattern
search_objects(object_type="procedure", schema="public", pattern="%report%", detail_level="summary")

# Find functions
search_objects(object_type="function", schema="public", detail_level="names")

常见模式

“我们有哪些数据？”

1. 列出架构 → 以 summary 详细程度列出表 → 选择相关表 → 以 full 详细程度检查

“从数据库中获取 X”

1. 搜索与 X 相关的表 → 检查列 → 编写有针对性的 SELECT

“这些表之间有什么关系？”

1. 以 full 详细程度检查两张表（列和索引可揭示外键及联接列）

“运行这条特定 SQL”

如果用户提供了准确的 SQL，可以直接执行。但如果执行失败并提示列或表错误，请改用探索工作流，而不是猜测如何修复。

错误恢复

查询失败时：

• 表或列未知：使用 search_objects 查找正确名称，而不是猜测可能的变体
• 架构错误：先列出可用架构——该表可能位于与预期不同的架构中
• 权限错误：数据库可能处于只读模式；检查是否只允许 SELECT 语句
• 多条语句：execute_sql 支持使用 ; 分隔的多条 SQL 语句

不要这样做

• 不要猜测表名或列名。 始终先用 search_objects 验证。猜错会浪费一次往返，还会让对话变得混乱。
• 不要一开始就倾倒整个架构。 采用渐进式披露——从 names 开始，只对实际要查询的表深入查看 full。
• 在多数据库设置中，不要使用错误的工具。 如果用户提到了特定数据库，请调用对应数据源的工具变体（例如 execute_sql_prod_pg），而不是通用的 execute_sql。
• 不要盲目重试失败的查询。 如果 SQL 执行失败，先调查架构以了解原因，再重试。