# Gerenciador de bancos de dados

Explore e edite PostgreSQL e MySQL do VPS pelo painel ou via MCP, por túnel privado, com proteções e auditoria.

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

- Categoria: Servidores e infraestrutura
- Estado: Disponível
- Requisitos: Um VPS ativo com PostgreSQL ou MySQL/MariaDB instalado; Ser membro da empresa com acesso a esse VPS
- Ferramentas MCP (Só leem): `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`
- Ferramentas MCP (Escrevem ou modificam): `guardar_credencial_db_vps`, `insertar_fila_db_vps`
- Ferramentas MCP (Destrutivas): `actualizar_fila_db_vps`, `borrar_fila_db_vps`, `ejecutar_ddl_db_vps`

## O que permite fazer?

O gerenciador de bancos de dados é a janela da ArduMaker para os motores PostgreSQL e MySQL que rodam dentro do VPS. Funciona igual pelo painel, pelo console interativo e via MCP: uma única implementação por motor.

- Ver motores, bancos (tamanho e codificação), tabelas e views com quantidade estimada de linhas.
- Descrever uma tabela: colunas com tipo normalizado, nulos, chave primária, chaves estrangeiras e índices.
- Ler linhas com filtros e ordem sem escrever SQL, com paginação por chave.
- Inserir, editar ou apagar uma linha pela sua chave primária completa.
- Console SQL somente leitura e `EXPLAIN`.
- Executar DDL (`CREATE`, `ALTER`, `DROP`, `TRUNCATE`) com confirmação por nome quando destrói dados.
- Exportar tabelas para CSV ou Excel e importar CSV ou Excel (até 32 MB) em dois passos.
- Ver o histórico de operações destrutivas: quem, quando, qual instrução e de onde.

## Quando convém usar?

- Verificar dados de produção sem abrir o motor para a internet nem instalar um cliente.
- Dar a um agente de IA acesso controlado ao banco, com escritas linha por linha e auditoria.
- Carregar uma planilha em uma tabela verificando antes como vai entrar.

## Como funciona na ArduMaker?

O backend chega ao motor por um túnel SSH privado até o VPS, com uma chave efêmera que só permite encaminhar para a porta do motor. A porta do banco não é publicada para isso: o [PostgreSQL](https://ardumaker.com/pt/docs/postgresql) e o [MySQL](https://ardumaker.com/pt/docs/mysql) continuam escutando só dentro do VPS.

1. Permissões: a empresa, o escopo MCP do agente sobre esse VPS e as listas de membros permitidos ou excluídos do VPS.
2. Túnel e conexão: o túnel é aberto ou reutilizado e validado com `SELECT 1`.
3. Credencial: a guardada para esse motor (se o cliente mudou a senha à mão e a cadastrou) ou a administrativa da plataforma.
4. Operação: o SQL é montado pela camada de cada motor com listas brancas; os valores sempre viajam como parâmetros do driver, nunca colados no texto.
5. Auditoria: o que escreve ou destrói fica no histórico com sua origem (interface ou agente).

## O que muda realmente?

Ler não muda nada. Escrever linhas, executar DDL e importar mudam dados do cliente dentro do motor; criar tabelas pelo formulário também, e é auditado como escrita. No VPS, o túnel usa um usuário próprio com uma chave restrita que não abre um shell.

| Operação | Regra |
| --- | --- |
| Console SQL | Uma única instrução de leitura; até 1000 linhas por página |
| Atualizar ou apagar linhas | Uma linha por vez, pela chave primária completa; não há atualização em massa |
| DDL destrutivo | Responde 428 com `confirmacion_esperada`; repete-se passando esse nome exato |
| Importar | Passo 1 `dry_run` analisa sem tocar; passo 2 exige o nome da tabela como confirmação |
| `EXPLAIN ANALYZE` | Executa a consulta de verdade; só PostgreSQL |

## Diferenças entre motores

- No PostgreSQL uma tabela pode ter esquema (`esquema.tabela`); no MySQL o esquema é o banco.
- `EXPLAIN` devolve o formato próprio de cada motor; não são comparáveis.
- A quantidade de linhas de `listar_tablas_db_vps` é a estimativa do motor; a contagem exata é `contar_filas_db_vps`, mais cara em tabelas grandes.

## Esquema

**Do painel ou do agente ao motor**

```text
Painel ou agente MCP (mesmo serviço e mesmas permissões)
  ↓
Backend da ArduMaker (permissões, guardas e auditoria)
  ↓
Túnel SSH privado (chave efêmera, só para a porta do motor)
  ↓
Motor no VPS (PostgreSQL `127.0.0.1:5432` ou MySQL `127.0.0.1:3306`)
```

## Resultado esperado

`probar_conexion_db_vps` confirma que o backend chega e entra no motor. A partir daí, `listar_bases_db_vps`, `listar_tablas_db_vps` e `describir_tabla_db_vps` mostram a estrutura e `leer_filas_db_vps` os dados. Cada escrita devolve a linha como ficou, com valores padrão e autoincrementos resolvidos.

## Erros e resolução

| Erro | Causa |
| --- | --- |
| `vps_apagado` | O VPS não está `active` |
| `credenciales_invalidas` | O motor recusa o usuário ou a senha (alguém a mudou à mão): cadastrá-la com `guardar_credencial_db_vps` |
| `credenciales_requeridas` | Não há credencial guardada nem uma administrativa utilizável |
| `motor_no_responde` | O túnel está aberto mas o motor não aceita a conexão ou `SELECT 1` falha |
| `tunel_no_disponible` / `clave_tunel_rechazada` | Não foi possível preparar o túnel; a chave é regenerada e tentada de novo uma vez sozinha |
| `pool_agotado` | Foi atingido o limite de conexões simultâneas para esse banco |
| `consulta_fallida` | O motor recusou a operação (sintaxe, restrição, permissões); a mensagem chega higienizada |
| `acceso_denegado` | Não é da empresa, está excluído do VPS ou o agente não tem esse VPS no escopo |

> **PELIGRO:** No MySQL cada DDL faz `COMMIT` implícito e não tem volta: a resposta diz se foi transacional (`transaccional`).

## Relação com MCP

O gerenciador completo está disponível via MCP; referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs) e [/mcp/bases-de-datos](https://ardumaker.com/pt/mcp/bases-de-datos). Todas as ferramentas recebem `engine` (`postgres` ou `mysql`) e, exceto as de motores, a `base`.

| Tipo | Ferramentas |
| --- | --- |
| Leitura | `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` |
| Modificam | `insertar_fila_db_vps`, `guardar_credencial_db_vps` |
| Destrutivas | `actualizar_fila_db_vps`, `borrar_fila_db_vps`, `ejecutar_ddl_db_vps` |

- `consultar_sql_db_vps` recusa escritas de propósito e uma segunda instrução separada por `;`. Os valores vão em `params`.
- `ejecutar_ddl_db_vps` destrutivo exige repetir com `confirmacion` igual a `confirmacion_esperada`; confirmar um nome errado é recusado.
- `guardar_credencial_db_vps` guarda a senha do motor criptografada e nenhuma ferramenta a devolve.
- Exportar e importar arquivos só existem no painel.

## Funcionalidades relacionadas

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