# Gestor de bases de datos

Explora y edita PostgreSQL y MySQL del VPS desde el panel o por MCP, por túnel privado, con guardas y auditoría.

Fuente: https://ardumaker.com/docs/gestor-de-bases-de-datos/

- Categoría: Servidores e infraestructura
- Estado: Disponible
- Requisitos: Un VPS activo con PostgreSQL o MySQL/MariaDB instalado; Ser miembro de la empresa con acceso a ese VPS
- Herramientas MCP (Solo leen): `listar_motores_db_vps`, `probar_conexion_db_vps`, `listar_bases_db_vps`, `listar_tablas_db_vps`, `describir_tabla_db_vps`, `leer_filas_db_vps`, `contar_filas_db_vps`, `consultar_sql_db_vps`, `explicar_sql_db_vps`, `historial_operaciones_db_vps`
- Herramientas MCP (Escriben o modifican): `guardar_credencial_db_vps`, `insertar_fila_db_vps`
- Herramientas MCP (Destructivas): `actualizar_fila_db_vps`, `borrar_fila_db_vps`, `ejecutar_ddl_db_vps`

## ¿Qué permite hacer?

El gestor de bases de datos es la ventana de ArduMaker a los motores PostgreSQL y MySQL que corren dentro del VPS. Funciona igual desde el panel, desde la consola interactiva y por MCP: una sola implementación por motor.

- Ver motores, bases (tamaño y codificación), tablas y vistas con cantidad estimada de filas.
- Describir una tabla: columnas con tipo normalizado, nulos, clave primaria, claves foráneas e índices.
- Leer filas con filtros y orden sin escribir SQL, con paginado por clave.
- Insertar, editar o borrar una fila por su clave primaria completa.
- Consola SQL de solo lectura y `EXPLAIN`.
- Ejecutar DDL (`CREATE`, `ALTER`, `DROP`, `TRUNCATE`) con confirmación por nombre cuando destruye datos.
- Exportar tablas a CSV o Excel e importar CSV o Excel (hasta 32 MB) en dos pasos.
- Ver el historial de operaciones destructivas: quién, cuándo, qué sentencia y desde dónde.

## ¿Cuándo conviene usarlo?

- Revisar datos de producción sin abrir el motor a internet ni instalar un cliente.
- Darle a un agente de IA acceso controlado a la base, con escrituras fila por fila y auditoría.
- Cargar una planilla en una tabla revisando antes cómo va a entrar.

## ¿Cómo funciona en ArduMaker?

El backend llega al motor por un túnel SSH privado hacia el VPS, con una clave efímera que solo permite reenviar al puerto del motor. El puerto de la base no se publica para esto: [PostgreSQL](https://ardumaker.com/docs/postgresql) y [MySQL](https://ardumaker.com/docs/mysql) siguen escuchando solo dentro del VPS.

1. Permisos: la empresa, el alcance MCP del agente sobre ese VPS y las listas de miembros permitidos o excluidos del VPS.
2. Túnel y conexión: se abre o reusa el túnel y se valida con `SELECT 1`.
3. Credencial: la guardada para ese motor (si el cliente cambió la clave a mano y la cargó) o la administrativa de la plataforma.
4. Operación: el SQL lo arma la capa de cada motor con listas blancas; los valores viajan siempre como parámetros del driver, nunca pegados al texto.
5. Auditoría: lo que escribe o destruye queda en el historial con su origen (interfaz o agente).

## ¿Qué cambia realmente?

Leer no cambia nada. Escribir filas, ejecutar DDL e importar cambian datos del cliente dentro del motor; crear tablas desde el formulario también, y se audita como escritura. En el VPS, el túnel usa un usuario propio con una clave restringida que no abre una shell.

| Operación | Regla |
| --- | --- |
| Consola SQL | Una sola sentencia, de lectura; hasta 1000 filas por página |
| Actualizar o borrar filas | Una fila por vez, por clave primaria completa; no hay actualización masiva |
| DDL destructivo | Responde 428 con `confirmacion_esperada`; se repite pasando ese nombre exacto |
| Importar | Paso 1 `dry_run` analiza sin tocar; paso 2 exige el nombre de la tabla como confirmación |
| `EXPLAIN ANALYZE` | Ejecuta la consulta de verdad; solo PostgreSQL |

## Diferencias entre motores

- En PostgreSQL una tabla puede llevar esquema (`esquema.tabla`); en MySQL el esquema es la base.
- `EXPLAIN` devuelve el formato propio de cada motor; no son comparables.
- La cantidad de filas de `listar_tablas_db_vps` es la estimación del motor; el conteo exacto es `contar_filas_db_vps`, más caro en tablas grandes.

## Esquema

**Del panel o el agente al motor**

```text
Panel o agente MCP (mismo servicio y mismos permisos)
  ↓
Backend de ArduMaker (permisos, guardas y auditoría)
  ↓
Túnel SSH privado (clave efímera, solo al puerto del motor)
  ↓
Motor en el VPS (PostgreSQL `127.0.0.1:5432` o MySQL `127.0.0.1:3306`)
```

## Resultado esperado

`probar_conexion_db_vps` confirma que el backend llega y entra al motor. A partir de ahí, `listar_bases_db_vps`, `listar_tablas_db_vps` y `describir_tabla_db_vps` muestran la estructura y `leer_filas_db_vps` los datos. Cada escritura devuelve la fila como quedó, con valores por defecto y autoincrementos resueltos.

## Errores y resolución

| Error | Causa |
| --- | --- |
| `vps_apagado` | El VPS no está `active` |
| `credenciales_invalidas` | El motor rechaza el usuario o la contraseña (alguien la cambió a mano): cargarla con `guardar_credencial_db_vps` |
| `credenciales_requeridas` | No hay credencial guardada ni una administrativa utilizable |
| `motor_no_responde` | El túnel está abierto pero el motor no acepta la conexión o falla `SELECT 1` |
| `tunel_no_disponible` / `clave_tunel_rechazada` | No se pudo preparar el túnel; la clave se regenera y se reintenta una vez sola |
| `pool_agotado` | Se alcanzó el tope de conexiones simultáneas para esa base |
| `consulta_fallida` | El motor rechazó la operación (sintaxis, restricción, permisos); el mensaje llega saneado |
| `acceso_denegado` | No es de la empresa, está excluido del VPS o el agente no tiene ese VPS en su alcance |

> **PELIGRO:** En MySQL cada DDL hace `COMMIT` implícito y no tiene vuelta atrás: la respuesta dice si fue transaccional (`transaccional`).

## Relación con MCP

El gestor completo está disponible por MCP; referencia en [/mcp/docs](https://ardumaker.com/mcp/docs) y [/mcp/bases-de-datos](https://ardumaker.com/mcp/bases-de-datos). Todas las herramientas reciben `engine` (`postgres` o `mysql`) y, salvo las de motores, la `base`.

| Tipo | Herramientas |
| --- | --- |
| Lectura | `listar_motores_db_vps`, `probar_conexion_db_vps`, `listar_bases_db_vps`, `listar_tablas_db_vps`, `describir_tabla_db_vps`, `leer_filas_db_vps`, `contar_filas_db_vps`, `consultar_sql_db_vps`, `explicar_sql_db_vps`, `historial_operaciones_db_vps` |
| Modifican | `insertar_fila_db_vps`, `guardar_credencial_db_vps` |
| Destructivas | `actualizar_fila_db_vps`, `borrar_fila_db_vps`, `ejecutar_ddl_db_vps` |

- `consultar_sql_db_vps` rechaza escrituras a propósito y una segunda sentencia separada por `;`. Los valores van en `params`.
- `ejecutar_ddl_db_vps` destructivo exige repetir con `confirmacion` igual a `confirmacion_esperada`; confirmar un nombre equivocado se rechaza.
- `guardar_credencial_db_vps` guarda cifrada la contraseña del motor y ninguna herramienta la devuelve.
- Exportar e importar archivos solo existen en el panel.

## Funciones relacionadas

- [PostgreSQL](https://ardumaker.com/docs/postgresql/)
- [MySQL](https://ardumaker.com/docs/mysql/)
- [Auditoría de agentes](https://ardumaker.com/docs/auditoria-de-agentes/)
- [Servidor MCP](https://ardumaker.com/docs/servidor-mcp/)
- [Túneles SSH](https://ardumaker.com/docs/tuneles-ssh/)