db-insight

db-insight

CLI de insight SQL local-first e servidor MCP para Postgres e SQLite.

Posicionamento: conecte uma réplica somente leitura, banco de dados analítico ou banco de dados de staging. Mantenha as credenciais na sua máquina enquanto a ferramenta descobre o esquema, gera SQL seguro, pré-visualiza para aprovação, executa a consulta e resume o resultado.

Instalação

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Configuração

Crie .env:

Postgres:

DATABASE_URL=postgresql://readonly:password@localhost:5432/app_db
DB_INSIGHT_MODEL=gemma3:latest
DB_INSIGHT_OLLAMA_URL=http://localhost:11434

SQLite:

DATABASE_URL=sqlite:///absolute/path/to/app.sqlite
DB_INSIGHT_MODEL=gemma3:latest
DB_INSIGHT_OLLAMA_URL=http://localhost:11434

Se o seu provedor fornecer uma URL com caracteres especiais, coloque-a entre aspas:

DATABASE_URL="postgresql://readonly:password@host.example.com:5432/app_db"

DB_INSIGHT_MODEL é configurável para que você possa usar a melhor tag Gemma/Ollama disponível na sua máquina.

CLI

db-insight connect
db-insight schema --refresh
db-insight ask "Why did revenue drop last week?"

Por padrão, ask usa o mesmo fluxo estilo MCP que o servidor:

user question
→ LLM plans tool calls
→ discover_schema / schema memory
→ generate_safe_sql
→ preview SQL for approval
→ run_approved_sql
→ summarize_results

A CLI voltada ao usuário pré-visualiza o SQL gerado e pergunta antes de executá-lo.

db-insight schema --refresh armazena um snapshot local de memória do esquema em .db-insight/schema_memory.json. Perguntas posteriores reutilizam essa imagem do esquema para que o modelo não precise redescobrir a mesma estrutura do banco de dados toda vez. A memória contém apenas metadados, não linhas de tabelas.

Servidor MCP stdio

Para a arquitetura de chat do anel de saúde Android, consulte Implementação de Chat do Android Health.

db-insight mcp

Isso expõe ferramentas locais seguras via stdio para clientes MCP:

• plan_tool_calls
• discover_schema
• refresh_schema_memory
• schema_memory_status
• catalog_overview
• inspect_table
• explain_sql
• generate_safe_sql
• run_approved_sql
• ask_database

Em um cliente MCP completo, o LLM decide quais ferramentas chamar. ask_database é uma ferramenta de conveniência que executa esse loop de decisão dentro deste servidor local, ainda exigindo aprovação explícita antes da execução.

Servidor MCP remoto

Para uso em equipe, execute o mesmo servidor via HTTP:

DB_INSIGHT_MCP_HOST=0.0.0.0 \
DB_INSIGHT_MCP_PORT=8000 \
db-insight mcp --transport streamable-http

O endpoint MCP HTTP é:

http://your-host:8000/mcp

Coloque-o atrás da sua camada de autenticação existente, VPN ou rede privada. Não exponha um servidor MCP com banco de dados diretamente à internet pública.

Docker

Construa a imagem:

docker build -t db-insight:latest .

Ou use a imagem publicada:

docker pull ghcr.io/enclavex-labs/db-insight:latest

Instale o Gemma no servidor Docker host:

ollama pull gemma3:latest

Configure seu cliente MCP para iniciar o contêiner via stdio.

Postgres:

{
  "mcpServers": {
    "db-insight": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "DATABASE_URL",
        "-e",
        "DB_INSIGHT_MODEL",
        "-e",
        "DB_INSIGHT_OLLAMA_URL",
        "ghcr.io/enclavex-labs/db-insight:latest"
      ],
      "env": {
        "DATABASE_URL": "postgresql://readonly:password@host.docker.internal:5432/app_db",
        "DB_INSIGHT_MODEL": "gemma3:latest",
        "DB_INSIGHT_OLLAMA_URL": "http://host.docker.internal:11434"
      }
    }
  }
}

SQLite:

{
  "mcpServers": {
    "db-insight": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-v",
        "/absolute/path/to/data:/data:ro",
        "-e",
        "DATABASE_URL",
        "-e",
        "DB_INSIGHT_MODEL",
        "-e",
        "DB_INSIGHT_OLLAMA_URL",
        "ghcr.io/enclavex-labs/db-insight:latest"
      ],
      "env": {
        "DATABASE_URL": "sqlite:////data/app.sqlite",
        "DB_INSIGHT_MODEL": "gemma3:latest",
        "DB_INSIGHT_OLLAMA_URL": "http://host.docker.internal:11434"
      }
    }
  }
}

Para VS Code/Copilot, use o mesmo corpo em servers em vez de mcpServers.

Cada usuário preenche DATABASE_URL com sua própria string de conexão Postgres ou URL de arquivo SQLite. Para SQLite no Docker, monte a pasta que contém o banco de dados em /data e use quatro barras: sqlite:////data/app.sqlite.

Para Postgres, se DATABASE_URL usar localhost ou 127.0.0.1, a imagem Docker o remapeia para host.docker.internal automaticamente.

Se você precisar de um endpoint HTTP compartilhado de longa duração, execute:

docker run --rm -p 8000:8000 \
  --add-host=host.docker.internal:host-gateway \
  -e DATABASE_URL=postgresql://readonly:password@host.docker.internal:5432/app_db \
  -e DB_INSIGHT_OLLAMA_URL=http://host.docker.internal:11434 \
  ghcr.io/enclavex-labs/db-insight:latest db-insight mcp --transport streamable-http