/dbhub

name: dbhub
description: Guide for querying databases through DBHub MCP server. Use this skill whenever you need to explore database schemas, inspect tables, or run SQL queries via DBHub's MCP tools (search_objects, execute_sql, and the opt-in explain_sql and health_check). Activates on any database query task, schema exploration, data retrieval, or SQL execution through MCP — even if the user just says "check the database" or "find me some data." This skill ensures you follow the correct explore-first workflow instead of guessing table structures.

DBHub Database Query Guide

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.

Available Tools

DBHub provides two MCP tools by default, plus opt-in ones:

| Tool | Purpose | |------|---------| | `search_objects` | Explore database structure — schemas, tables, columns, indexes, procedures, functions | | `execute_sql` | Run SQL statements against the database | | `explain_sql` (opt-in) | Show a query's execution plan without running it — only present if the source's config enables it | | `health_check` (opt-in) | Report connection pool state and buffer cache hit ratio — only present if the source's config enables it; PostgreSQL, MySQL, MariaDB, and SQL Server only |

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.

If `explain_sql` is available (check the tool list), prefer it over guessing whether a query will be efficient — it's always safe to call, even against a write-enabled or read-only source, since it never executes the statement.

If `health_check` is available and a query seems slow or connections seem exhausted, call it before speculating — it reports live connection pool and cache-hit numbers instead of guessing at the cause.

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

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.

Step 2: Find relevant tables

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.

Step 3: Inspect table structure

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

Step 4: Write and execute the query

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

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.

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}`:

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

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.

Searching for Specific Objects

The `search_objects` tool supports targeted searches across all object types:

# 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="p