dbhub

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DBHub Database Query Guide

DBHub数据库查询指南

When working with databases through DBHub's MCP server, always follow the explore-then-query pattern. Jumping straight to SQL without understanding the schema is the most common mistake — it leads to failed queries, wasted tokens, and frustrated users.

通过DBHub的MCP服务器操作数据库时，请始终遵循先探索再查询的模式。不了解架构就直接编写SQL是最常见的错误——这会导致查询失败、浪费令牌并使用户受挫。

Available Tools

可用工具

DBHub provides two MCP tools:

Tool	Purpose
`search_objects`	Explore database structure — schemas, tables, columns, indexes, procedures, functions
`execute_sql`	Run SQL statements against the database

If multiple databases are configured, DBHub registers separate tools for each source (for example,

search_objects_prod_pg

execute_sql_staging_mysql

). Select the desired database by calling the correspondingly named tool.

DBHub提供两种MCP工具：

工具	用途
`search_objects`	探索数据库结构——架构、表、列、索引、存储过程、函数
`execute_sql`	在数据库上运行SQL语句

如果配置了多个数据库，DBHub会为每个数据源注册独立的工具（例如

search_objects_prod_pg

、

execute_sql_staging_mysql

）。通过调用对应名称的工具来选择目标数据库。

The Explore-Then-Query Workflow

先探索再查询的工作流

Every database task should follow this progression. The key insight is that each step narrows your focus, so you never waste tokens loading information you don't need.

所有数据库任务都应遵循以下流程。核心要点是每一步都缩小你的关注范围，因此你永远不会浪费令牌加载不需要的信息。

Step 1: Discover what schemas exist

步骤1：发现现有架构

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

This tells you the lay of the land. Most databases have a primary schema (e.g.,

public

in PostgreSQL,

dbo

in SQL Server) plus system schemas you can ignore.

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

这会让你了解整体情况。大多数数据库都有一个主架构（例如PostgreSQL中的

public

、SQL Server中的

dbo

）以及可忽略的系统架构。

Step 2: Find relevant tables

步骤2：查找相关表

Once you know the schema, list its tables:

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

If you're looking for something specific, use a pattern:

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

The

pattern

parameter uses SQL LIKE syntax:

matches any characters,

matches a single character.

If you need more context to identify the right table (row counts, column counts, table comments), use

detail_level="summary"

instead.

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

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"

。

Step 3: Inspect table structure

步骤3：查看表结构

Before writing any query, understand the columns:

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

This returns column names, data types, nullability, and defaults — everything you need to write correct SQL.

For understanding query performance or join patterns, also check indexes:

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

编写任何查询之前，请先了解列信息：

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")

Step 4: Write and execute the query

步骤4：编写并执行查询

Now that you know the exact table and column names, write precise SQL:

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

了解确切的表和列名后，编写精准的SQL：

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

Progressive Disclosure: Choosing the Right Detail Level

渐进式披露：选择合适的详细级别

The

detail_level

parameter controls how much information

search_objects

returns. Start minimal and drill down only where needed — this keeps responses fast and token-efficient.

Level	What you get	When to use
`names`	Just object names	Browsing, finding the right table
`summary`	Names + metadata (row count, column count, comments)	Choosing between similar tables, understanding data volume
`full`	Complete structure (columns with types, indexes, procedure definitions)	Before writing queries, understanding relationships

Rule of thumb: Use

names

for broad exploration,

summary

for narrowing down, and

full

only for the specific tables you'll query.

detail_level

参数控制

search_objects

返回的信息量。从最小粒度开始，仅在需要时深入——这能让响应更快且令牌使用更高效。

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

经验法则： 使用

names

进行大范围探索，使用

summary

缩小范围，仅对要查询的特定表使用

full

。

Working with Multiple Databases

多数据库场景下的操作

When DBHub is configured with multiple database sources, it registers separate tool instances for each source. The tool names follow the pattern

{tool}_{source_id}

undefined

当DBHub配置了多个数据库源时，会为每个源注册独立的工具实例。工具名称遵循

{tool}_{source_id}

的模式：

undefined

Query the production PostgreSQL database

查询生产环境PostgreSQL数据库

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

查询预发布环境MySQL数据库

search_objects_staging_mysql(object_type="table", detail_level="names") execute_sql_staging_mysql(sql="SELECT count(*) FROM orders")


In single-database setups, the tools are simply `search_objects` and `execute_sql` without any suffix. When the user mentions a specific database or environment, call the correspondingly named tool.

search_objects_staging_mysql(object_type="table", detail_level="names") execute_sql_staging_mysql(sql="SELECT count(*) FROM orders")


在单数据库配置中，工具名称就是`search_objects`和`execute_sql`，没有后缀。当用户提到特定数据库或环境时，调用对应名称的工具。

Searching for Specific Objects

查找特定对象

The

search_objects

tool supports targeted searches across all object types:

undefined

search_objects

工具支持跨所有对象类型的定向搜索：

undefined

Find all tables with "order" in the name

查找所有名称包含"order"的表

search_objects(object_type="table", pattern="%order%", detail_level="names")

Find columns named "email" across all tables

查找所有表中名为"email"的列

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")

undefined

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

undefined

Common Patterns

常见模式

"What data do we have?"

“我们有哪些数据？”

List schemas → list tables with
```
summary
```
detail → pick relevant tables → inspect with
```
full
```
detail

列出架构 → 以
```
summary
```
级别列出表 → 选择相关表 → 以
```
full
```
级别查看细节

"Get me X from the database"

“帮我从数据库中获取X数据”

Search for tables related to X → inspect columns → write targeted SELECT

搜索与X相关的表 → 查看列信息 → 编写定向SELECT语句

"How are these tables related?"

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

Inspect both tables at
```
full
```
detail (columns + indexes reveal foreign keys and join columns)

以
```
full
```
级别查看两个表的细节（列和索引会揭示外键和关联列）

"Run this specific SQL"

“运行这条特定的SQL”

If the user provides exact SQL, you can execute it directly. But if it fails with a column or table error, fall back to the explore workflow rather than guessing fixes.

如果用户提供了确切的SQL，你可以直接执行。但如果因列或表错误导致执行失败，请回到探索工作流，而非猜测修复方案。

Error Recovery

错误恢复

When a query fails:

Unknown table/column: Use
```
search_objects
```
to find the correct names rather than guessing variations
Schema errors: List available schemas first — the table may be in a different schema than expected
Permission errors: The database may be in read-only mode; check if only SELECT statements are allowed
Multiple statements:
```
execute_sql
```
supports multiple SQL statements separated by
```
;
```

当查询失败时：

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

What NOT to Do

禁止操作

Don't guess table or column names. Always verify with
```
search_objects
```
first. A wrong guess wastes a round trip and confuses the conversation.
Don't dump entire schemas upfront. Use progressive disclosure — start with
```
names
```
, drill into
```
full
```
only for tables you'll actually query.
Don't use the wrong tool in multi-database setups. If the user mentions a specific database, call the source-specific tool variant (e.g.,
```
execute_sql_prod_pg
```
) rather than the generic
```
execute_sql
```
.
Don't retry failed queries blindly. If SQL fails, investigate the schema to understand why before retrying.

不要猜测表或列名称：务必先通过
```
search_objects
```
验证。错误的猜测会浪费一次交互并混淆对话流程。
不要预先导出整个架构：使用渐进式披露——从
```
names
```
开始，仅对要查询的表使用
```
full
```
级别。
在多数据库场景下不要使用错误的工具：如果用户提到特定数据库，请调用对应源的工具变体（例如
```
execute_sql_prod_pg
```
），而非通用的
```
execute_sql
```
。
不要盲目重试失败的查询：如果SQL执行失败，请先调查架构以了解原因，再进行重试。