DBHub: la base de datos como herramienta del agente

Con DBHub el agente puede leer tablas y ejecutar SQL durante una sesión de testing. Esta guía explica qué archivo configurar, qué variables rellenar y cómo diagnosticar una conexión que falla.

SetupMCP

Qué es

DBHub (@bytebase/dbhub) es un servidor MCP que conecta el agente con una base de datos. En este repo es la herramienta principal para la pata de datos del testing: la tercera comprobación de /sprint-testing después de UI y API, la búsqueda de datos de prueba y la evidencia de un bug cuando lo que prueba el fallo es una fila y no una captura de pantalla.

Fuente canónica

La IA lee .agents/skills/agentic-qa-core/references/db-testing-doctrine.md. Esta página es la guía para personas; si alguna vez no coinciden, manda la doctrina.

Motores soportados, según el valor de DBHUB_TYPE: postgres, mysql, mariadb, sqlserver y sqlite.

Las tres piezas

Pieza Dónde Qué tiene Se commitea?
Configuración dbhub.toml (raíz del repo) Un bloque [[sources]] con id = "primary" y cada valor de conexión como placeholder ${DBHUB_*} Sí, no contiene secretos
Credenciales .env Las variables DBHUB_* con los valores reales Nunca
Servidor MCP .mcp.json, opencode.jsonc, .codex/config.toml El server dbhub, que arranca dbhub --config dbhub.toml (la versión está fijada en .mcp.json) detrás del loader de .env, que le pasa esas variables Sí, ya viene declarado

El archivo que trae el repo es este:

[[sources]]
id = "primary"
type = "${DBHUB_TYPE}"
host = "${DBHUB_HOST}"
port = "${DBHUB_PORT}"
database = "${DBHUB_DATABASE}"
user = "${DBHUB_USER}"
password = "${DBHUB_PASSWORD}"
sslmode = "require"

La sustitución de ${...} la hace el propio dbhub, con el entorno del proceso que lo lanzó. Por eso los tres harnesses (.mcp.json, opencode.jsonc y .codex/config.toml) arrancan dbhub con el mismo loader delante, varlock run ... --filter DBHUB_TYPE,...,DBHUB_PASSWORD -- <dbhub>: lee .env desde la raíz del proyecto al arrancar el server y le pasa exactamente esas seis variables, aunque abras el harness desde la app de escritorio.

Configurarlo paso a paso

  1. Rellena las variables en .env

    Copia los nombres de .env.example y pon los valores de tu base de datos. 

    DBHUB_TYPE=          # sqlserver | postgres | mysql | sqlite | mariadb
DBHUB_HOST=
DBHUB_PORT=          # 1433 sqlserver | 5432 postgres | 3306 mysql/mariadb
DBHUB_DATABASE=
DBHUB_USER=
DBHUB_PASSWORD=
  2. No toques dbhub.toml salvo que haga falta

    No lo borres, no lo metas en .gitignore y no escribas un valor literal en él. La única edición habitual es sslmode: el archivo trae require, y una base de datos local sin TLS necesita cambiar esa línea en tu copia del proyecto. El updater (bun sync) nunca sobrescribe este archivo.

  3. Arranca el agente

    Abre la sesión con claude, opencode o codex en la carpeta del repo, o con su app de escritorio. dbhub lee .env por su cuenta con el loader de varlock. Si exportaste una variable DBHUB_* en el perfil de tu shell, esa gana sobre el archivo; bun run vars:env:check la nombra. Si cambias .env con la sesión abierta, reiníciala: el MCP recibe las variables una sola vez, al arrancar.

  4. Comprueba la conexión

    En Claude Code, /mcp lista los servidores; dbhub debe aparecer como conectado. Después pide algo simple, por ejemplo "mira la base de datos y dime cuántas tablas hay". Si el agente llama a search_objects_primary y devuelve resultados, la conexión funciona.

Una variable vacía no avisa al arrancar

Si falta una variable, dbhub no se detiene: sustituye el texto literal (por ejemplo ${DBHUB_PASSWORD}) y la conexión falla en la primera query, con un error que parece de la base de datos. Ante cualquier fallo raro de DBHub, mira primero qué DBHUB_* están definidas con bunx varlock load --agent --filter 'DBHUB_*' (sin mostrar valores), corrige .env y reinicia la sesión.

Herramientas que recibe el agente

DBHub nombra sus herramientas como {herramienta}_{id de la fuente}. Como dbhub.toml trae una sola fuente con id = "primary", el agente ve dos:

Herramienta Para qué
search_objects_primary Explorar schemas, tablas y columnas antes de escribir una query
execute_sql_primary Ejecutar la query

Qué validar con ellas (existencia de filas, valores, huérfanos, duplicados, timestamps) y las queries de ejemplo están en el SQL cookbook.

Un usuario de base de datos para QA

Para validar datos basta con SELECT. Pide permisos de escritura solo en un entorno que no sea producción y solo si un test necesita sembrar datos directamente. Si tu equipo ya tiene un usuario compartido, pide las credenciales por el gestor de contraseñas. Si hay que crear uno, estos son los mínimos por motor (cambia <password> por una contraseña generada, nunca la escribas en el repo):

PostgreSQL 
CREATE USER qa_automation WITH PASSWORD '<password>';
GRANT SELECT ON ALL TABLES IN SCHEMA public TO qa_automation;
-- Solo si hace falta sembrar datos, fuera de producción:
-- GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO qa_automation;
SQL Server 
CREATE USER [qa_automation] WITH PASSWORD = '<password>';
ALTER ROLE db_datareader ADD MEMBER [qa_automation];
-- Solo si hace falta sembrar datos, fuera de producción:
-- ALTER ROLE db_datawriter ADD MEMBER [qa_automation];
MySQL / MariaDB 
CREATE USER 'qa_automation'@'%' IDENTIFIED BY '<password>';
GRANT SELECT ON tu_base_de_datos.* TO 'qa_automation'@'%';
-- Solo si hace falta sembrar datos, fuera de producción:
-- GRANT INSERT, UPDATE, DELETE ON tu_base_de_datos.* TO 'qa_automation'@'%';
FLUSH PRIVILEGES;

Más de una base de datos

Añade otro bloque [[sources]] a dbhub.toml con un id distinto y sus propias variables en .env. El sufijo del id es lo único que distingue las herramientas: una fuente con id = "reporting" añade execute_sql_reporting junto a execute_sql_primary. 

[[sources]]
id = "reporting"
type = "${REPORTING_DB_TYPE}"
host = "${REPORTING_DB_HOST}"
port = "${REPORTING_DB_PORT}"
database = "${REPORTING_DB_DATABASE}"
user = "${REPORTING_DB_USER}"
password = "${REPORTING_DB_PASSWORD}"
sslmode = "require"

Los nombres REPORTING_DB_* son un ejemplo. Sean cuales sean, tienen que llegar al proceso del MCP, así que decláralos también en el bloque dbhub de los tres archivos de harness, igual que las DBHUB_*.

Problemas de conexión

Síntoma Causa probable Qué revisar
Connection refused o no conecta al host La base no está levantada, el puerto es otro o un firewall bloquea tu IP DBHUB_HOST y DBHUB_PORT; en Postgres, pg_isready -h <host> -p <port>; que tu IP esté en la lista permitida del servidor
password authentication failed o Login failed Usuario o contraseña incorrectos, o llegó al servidor el texto literal ${DBHUB_PASSWORD} Las DBHUB_* de .env, luego reiniciar la sesión
Cannot open database El nombre de la base no coincide DBHUB_DATABASE; en algunos motores el nombre distingue mayúsculas
Errores de SSL o Server requires encryption El servidor y sslmode no coinciden El repo trae sslmode = "require"; una base local sin TLS necesita cambiar esa línea
too many connections Varias sesiones en paralelo que no cierran conexiones Menos workers en paralelo, o un pooler

Reglas de seguridad