db-insight

db-insight

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

Posicionamiento: conecta una réplica de solo lectura, base de datos analítica o base de datos de staging. Mantén las credenciales en tu máquina mientras la herramienta descubre el esquema, genera SQL seguro, lo previsualiza para aprobación, ejecuta la consulta y resume el resultado.

Instalación

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

Configuración

Crea .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

Si tu proveedor proporciona una URL con caracteres especiales, envuélvela entre comillas:

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

DB_INSIGHT_MODEL es configurable para que puedas usar la mejor etiqueta Gemma/Ollama disponible en tu máquina.

CLI

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

Por defecto, ask usa el mismo flujo estilo MCP que el servidor:

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

La CLI orientada al usuario previsualiza el SQL generado y pregunta antes de ejecutarlo.

db-insight schema --refresh almacena una instantánea local de memoria de esquema en .db-insight/schema_memory.json. Las preguntas posteriores reutilizan esa imagen del esquema para que el modelo no necesite redescubrir la misma estructura de base de datos cada vez. La memoria contiene solo metadatos, no filas de tablas.

Servidor MCP stdio

Para la arquitectura de chat de anillo de salud de Android, consulta Implementación de Android Health Chat.

db-insight mcp

Esto expone herramientas locales seguras a través de 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

En un cliente MCP completo, el LLM decide qué herramientas llamar. ask_database es una herramienta de conveniencia que realiza ese bucle de decisión dentro de este servidor local y aun así requiere aprobación explícita antes de la ejecución.

Servidor MCP remoto

Para uso en equipo, ejecuta el mismo servidor por HTTP:

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

El endpoint MCP HTTP es:

http://your-host:8000/mcp

Colócalo detrás de tu capa de autenticación, VPN o red privada existentes. No expongas un servidor MCP respaldado por base de datos directamente a la internet pública.

Docker

Construye la imagen:

docker build -t db-insight:latest .

O usa la imagen publicada:

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

Instala Gemma en el servidor Docker del host:

ollama pull gemma3:latest

Configura tu cliente MCP para lanzar el contenedor a través de 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, usa el mismo cuerpo bajo servers en lugar de mcpServers.

Cada usuario completa DATABASE_URL con su propia cadena de conexión de Postgres o URL de archivo SQLite. Para SQLite en Docker, monta la carpeta que contiene la base de datos en /data y usa cuatro barras: sqlite:////data/app.sqlite.

Para Postgres, si DATABASE_URL usa localhost o 127.0.0.1, la imagen Docker la reasigna a host.docker.internal automáticamente.

Si necesitas un endpoint HTTP compartido de larga duración, ejecuta:

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