DBeast

---

O DBeast conecta assistentes de IA como Claude, Cursor, Windsurf e VS Code Copilot ao PostgreSQL por meio do Model Context Protocol. Em vez de expor uma ampla porta de escape execute_sql, o DBeast fornece 21 ferramentas focadas para descoberta de esquema, execução segura de consultas, análise de impacto, revisão de desempenho, verificações de segurança, relatórios de manutenção, monitoramento de replicação e inspeção de qualidade de dados.

---

Demonstração

Assista ao Claude usar as ferramentas MCP do DBeast para auditar um banco de dados PostgreSQL, identificar riscos de segurança e manutenção e pré-visualizar o impacto da limpeza sem executar SQL destrutivo.

---

Como Funciona

AI assistant  --MCP stdio-->  DBeast server  --asyncpg-->  PostgreSQL
Claude/Cursor                  Python local                 Local, RDS,
Windsurf/VS Code               subprocess                   Supabase, Neon

O DBeast roda como um servidor MCP stdio local. Seu IDE ou assistente de desktop o inicia como um subprocesso e passa as credenciais do banco de dados por meio de variáveis de ambiente. O assistente chama as ferramentas do DBeast, o DBeast consulta o PostgreSQL e resultados estruturados retornam ao assistente. Nenhum serviço HTTP ou infraestrutura extra é necessário.

---

Início Rápido

1. Instalação

git clone https://github.com/snss10/DBeast.git
cd DBeast
pip install -e .

Para desenvolvimento:

pip install -e ".[dev]"

Opcional: copie .env.example para .env e defina suas credenciais do banco de dados.

2. Verificação

dbeast

Ou execute o ponto de entrada do código-fonte diretamente:

python src/server.py

3. Configure Seu Cliente MCP

Configuração mínima para Cursor ou Windsurf:

{
  "mcpServers": {
    "dbeast": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/DBeast/src/server.py"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

Locais comuns de configuração:

Cliente	Local da configuração
Cursor	.mcp.json na raiz do projeto, ou ~/.cursor/.mcp.json globalmente
VS Code	.vscode/settings.json ou configurações do usuário com a chave mcp.servers
Claude Desktop no macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop no Windows	%APPDATA%\Claude\claude_desktop_config.json
Windsurf	.mcp.json

Consulte SETUP.md para exemplos completos de clientes, Docker, RDS, Supabase, Neon, túneis SSH, AWS Secrets Manager e solução de problemas.

4. Faça Perguntas Simples ou Complexas

Uma vez conectado, seu assistente pode responder a perguntas rápidas de consulta e também executar investigações de banco de dados em várias etapas.

Exemplos simples:

Show me the schema for the orders table.
Which queries are slowest right now?
Run a security audit on the public schema.
Generate a Mermaid ERD for the sales schema.

Exemplos mais complexos:

Before I archive old sessions, estimate how many rows would be affected, identify related tables, and tell me the rollback risk.
Investigate why the dashboard query is slow, explain the execution plan, and suggest safe indexes.
Review the public schema for maintenance issues, security risks, and data quality problems, then summarize the top priorities.
Compare table growth, dead tuples, and index health across all schemas and recommend what to vacuum or reindex first.

---

Ferramentas

O DBeast expõe 21 ferramentas MCP em 10 categorias.

Conexão

Ferramenta	Descrição
connect	Conectar ao PostgreSQL, verificar o status atual ou descobrir bancos de dados locais
disconnect	Fechar a conexão atual com o banco de dados
health_check	Verificar conectividade, saúde do pool, versão do PostgreSQL e extensões

Descoberta de Esquema

Ferramenta	Descrição
get_schema	Listar esquemas, tabelas, colunas, índices, relacionamentos e ERDs Mermaid opcionais
dependency_analysis	Mapear dependências de objetos antes de renomear, excluir ou alterar objetos do banco de dados

Acesso a Dados

Ferramenta	Descrição
execute_query	Executar consultas SELECT somente leitura com injeção automática de limite de linhas

Análise de Consultas

Ferramenta	Descrição
analyze_query	Analisar e inspecionar a estrutura da consulta, avisos e dicas de otimização
query_optimizer	Recomendar índices e reescritas para uma determinada consulta
analyze_impact	Pré-visualizar o impacto de consultas de escrita, nível de risco, linhas afetadas e contexto de rollback sem executar

Saúde do Banco de Dados

Ferramenta	Descrição
database_health	Revisar taxas de acerto de cache, conexões, idade das transações, saúde das tabelas e sinais gerais de saúde
query_performance	Relatar consultas lentas ou caras a partir das estatísticas do PostgreSQL

Segurança

Ferramenta	Descrição
security_audit	Inspecionar papéis, privilégios, contas de superusuário e exposição do esquema público
sensitive_data_scan	Detectar possíveis PII ou segredos por nomes de colunas e padrões de esquema

Manutenção

Ferramenta	Descrição
maintenance_analysis	Revisar status de vacuum, tuplas mortas, timestamps de analyze e saúde dos índices
partition_analysis	Inspecionar saúde das partições, distribuição de linhas e riscos de partições ausentes

Qualidade de Dados

Ferramenta	Descrição
data_quality_report	Analisar taxas de nulos, cardinalidade, distribuições de valores e outliers
duplicate_detection	Encontrar linhas duplicadas entre colunas-chave selecionadas

Configuração do Servidor

Ferramenta	Descrição
configuration_review	Revisar a configuração do PostgreSQL e oportunidades de ajuste
replication_status	Inspecionar atraso de replicação, estado do WAL sender/receiver e slots de replicação

Auditoria

Ferramenta	Descrição
get_audit_logs	Recuperar chamadas de ferramentas MCP registradas para uma determinada data
list_audit_files	Listar arquivos de log de auditoria disponíveis

---

Fluxo de Trabalho Recomendado

Comece descobrindo esquemas:

get_schema()
get_schema(schema='public')

Execute consultas de leitura seguras:

execute_query(query='SELECT * FROM orders ORDER BY created_at DESC')

Pré-visualize escritas arriscadas:

analyze_impact(query='DELETE FROM sessions WHERE last_active < now() - interval ''30 days''')

Verifique saúde e manutenção:

database_health()
maintenance_analysis(schema='public')
query_performance()

A maioria das ferramentas de análise aceita um parâmetro schema:

maintenance_analysis(schema='public')  -> analyze one schema
maintenance_analysis(schema='all')     -> analyze every schema
get_schema(format='mermaid')           -> generate an ERD diagram

---

Bancos de Dados Suportados

Provedor	Método de conexão
PostgreSQL local	DATABASE_URL ou variáveis DB_* individuais
PostgreSQL Docker	Variáveis explícitas ou connect(discover=true)
AWS RDS / Aurora	URL direta, túnel SSH ou AWS Secrets Manager
Supabase	String de conexão do pooler nas configurações do Dashboard
Neon	String de conexão nos detalhes de conexão do Console
Railway / Render / Fly.io	String de conexão do provedor
Qualquer host PostgreSQL	URL PostgreSQL padrão

---

Configuração

Escolha um método de conexão.

# Full URL
DATABASE_URL=postgresql://user:pass@host:5432/db

# Or individual variables
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=secret
DB_NAME=mydb
DB_SSLMODE=prefer

# Or AWS Secrets Manager
AWS_SECRET_NAME=my-rds-secret
AWS_REGION=us-west-2

Você também pode conectar em tempo de execução:

connect(url='postgresql://user:pass@host:5432/db')
connect(host='localhost', user='postgres', password='secret', database='mydb')
connect(aws_secret_name='my-secret', aws_region='us-west-2')

Configurações principais:

Variável	Padrão	Descrição
DBEAST_DEFAULT_ROW_LIMIT	100	Máximo de linhas retornadas por execute_query
DBEAST_QUERY_TIMEOUT	300	Tempo limite de execução da consulta em segundos
DBEAST_COMMAND_TIMEOUT	300	Tempo limite do comando SQL em segundos
DBEAST_SSL_VERIFY	true	Defina false para túneis SSH onde os certificados não correspondem a localhost
DBEAST_SCHEMA_CACHE_TTL	60	TTL do cache de esquema em segundos, 0 desativa o cache
DBEAST_AUDIT_ENABLED	true	Registrar chamadas de ferramentas MCP
DBEAST_AUDIT_DIR	logs/mcp_audit	Diretório do log de auditoria

Consulte SETUP.md para a referência completa de configuração.

---

Modelo de Segurança

Tipo de consulta	O que o DBeast faz
SELECT	Executa com limites automáticos de linhas
INSERT / UPDATE / DELETE	Nunca executa; retorna uma pré-visualização de impacto
DROP / TRUNCATE	Nunca executa; relata objetos afetados e risco

Respostas formatadas e JSON usam um invólucro consistente:

{
  "success": true,
  "data": { "...": "..." },
  "meta": {
    "connected": true,
    "source": "tool"
  }
}

---

Registro de Auditoria

O DBeast registra chamadas de ferramentas MCP para responsabilidade e depuração.

DBEAST_AUDIT_ENABLED=true
DBEAST_AUDIT_DIR=logs/mcp_audit

Os arquivos de auditoria são armazenados como arquivos markdown diários e incluem timestamps, nomes de ferramentas, durações, parâmetros mascarados, respostas truncadas e erros.

---

Desenvolvimento

pip install -e ".[dev]"
pre-commit install
pytest tests/ -v
ruff check src/ tests/
ruff format src/ tests/

Inicie o banco de dados PostgreSQL local opcional para testes:

docker compose up -d postgres

Compose legado:

docker-compose up -d postgres

---

Documentação

• SETUP.md - Configuração completa do cliente, cenários de conexão, configuração e solução de problemas
• CONTRIBUTING.md - Configuração de desenvolvimento, testes, estilo, commits e processo de PR
• CODE_OF_CONDUCT.md - Diretrizes da comunidade

---

Licença

MIT