a2db

Agent: "Show me active users and their recent orders"
  ↓
a2db execute → 2 queries, 1 call, structured results
  ↓
Agent: "Got it — 847 active users, avg order $42.50"

¿Por qué a2db?

La mayoría de los servidores MCP de bases de datos te obligan a ejecutar una consulta a la vez, repetir los detalles de conexión en cada llamada y devolver resultados con doble codificación dentro de cadenas JSON. a2db soluciona todo eso:

• Conexiones preconfiguradas — define bases de datos en .mcp.json con --register, el agente consulta inmediatamente

• Consultas por lotes — ejecuta múltiples consultas con nombre en una sola llamada de herramienta

• Conexión predeterminada — establece la conexión una vez, úsala en todas las consultas de un lote

• Salida limpia — sobre JSON estructurado con datos TSV compactos y tiempos por consulta (ver ¿por qué TSV?)

• Solo lectura forzada — el análisis AST de SQLGlot bloquea todas las operaciones de escritura

• Todos los controladores incluidos — pip install a2db y listo

• Los secretos permanecen en el entorno — ${DB_PASSWORD} en los DSN, se expanden solo en el momento de la conexión

Bases de datos compatibles

Inicio rápido

pip install a2db

Como servidor MCP (recomendado)

Claude Code (con conexión preconfigurada):

claude mcp add -s user a2db -- a2db-mcp \
  --register myapp/prod/main 'postgresql://user:${DB_PASSWORD}@host/mydb'

Claude Code (mínimo — el agente llama a login bajo demanda):

claude mcp add -s user a2db -- a2db-mcp

Claude Desktop / Cursor / cualquier cliente MCP (.mcp.json):

{
  "mcpServers": {
    "a2db": {
      "command": "uvx",
      "args": [
        "a2db-mcp",
        "--register", "myapp/prod/main", "postgresql://user:${DB_PASSWORD}@host/mydb"
      ],
      "env": {
        "DB_PASSWORD": "your-password-here"
      }
    }
  }
}

Múltiples bases de datos:

{
  "args": [
    "a2db-mcp",
    "--register", "myapp/prod/main", "postgresql://user:${DB_PASSWORD}@host/maindb",
    "--register", "myapp/prod/analytics", "postgresql://user:${DB_PASSWORD}@host/analytics"
  ]
}

--register pre-registra las conexiones al iniciar el servidor — el agente puede consultar inmediatamente. Las contraseñas usan la sintaxis ${ENV_VAR} y se expanden en el momento de la conexión, nunca se almacenan en texto plano.

Como CLI

# Save a connection (validates immediately)
a2db login -p myapp -e prod -d main 'postgresql://user:${DB_PASSWORD}@localhost/mydb'

# Query
a2db query -p myapp -e prod -d main "SELECT * FROM users LIMIT 10"

# JSON output
a2db query -p myapp -e prod -d main -f json "SELECT * FROM users LIMIT 10"

# Explore schema
a2db schema -p myapp -e prod -d main tables
a2db schema -p myapp -e prod -d main columns -t users

# List / remove connections
a2db connections
a2db logout -p myapp -e prod -d main

Herramientas MCP

execute — la herramienta principal

Diccionario con nombre con conexión predeterminada (preferido):

{
  "connection": {"project": "myapp", "env": "prod", "db": "main"},
  "queries": {
    "active_users": {"sql": "SELECT id, name FROM users WHERE active = true"},
    "recent_orders": {"sql": "SELECT id, total FROM orders ORDER BY created_at DESC LIMIT 5"}
  }
}

Formato de lista (auto-nombrado q1, q2, ...):

{
  "connection": {"project": "myapp", "env": "prod", "db": "main"},
  "queries": [
    {"sql": "SELECT COUNT(*) AS cnt FROM users"},
    {"sql": "SELECT AVG(total) AS avg_order FROM orders"}
  ]
}

Respuesta (formato TSV — predeterminado):

{
  "active_users": {
    "data": "id\tname\n1\tAlice\n2\tBob\n3\tCharlie",
    "rows": 3,
    "truncated": false,
    "time_ms": 12
  },
  "recent_orders": {
    "data": "id\ttotal\n501\t129.00\n500\t49.99",
    "rows": 2,
    "truncated": false,
    "time_ms": 8
  }
}

No se necesitan conversiones ::text — enteros, flotantes, marcas de tiempo, matrices y NULLs funcionan de forma nativa.

Contexto de error

Cuando una consulta falla con un error de columna, a2db enriquece el mensaje:

column "nme" does not exist
Did you mean: name?
Available columns: id (integer), name (text), email (text), active (integer)

¿Por qué TSV?

Las ventanas de contexto de los LLM son costosas. Los datos de fila JSON son verbosos — cada fila repite cada nombre de columna, añade llaves, comas y comillas. TSV es una cuadrícula plana: una fila de encabezado, luego solo valores separados por tabulaciones.

Para un conjunto de resultados de 100 filas y 5 columnas, TSV suele utilizar entre un 40-60% menos de tokens que el formato de fila JSON. El sobre JSON estructurado sigue proporcionando metadatos (recuento de filas, estado de truncamiento) — solo la carga útil de la fila es TSV.

Establece format="json" si necesitas una salida estructurada completa con nombres de columna en cada fila.

Seguridad

Cumplimiento de solo lectura

Cada consulta es analizada por SQLGlot antes de su ejecución:

• Bloqueado: INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, GRANT, REVOKE

• Resistente a bypass: los ataques de múltiples sentencias y las escrituras envueltas en comentarios se detectan a nivel de AST, no solo mediante coincidencia de palabras clave

• Permitido: SELECT, UNION, EXPLAIN, SHOW, DESCRIBE, PRAGMA

Esto es defensa en profundidad — también deberías usar un usuario de base de datos de solo lectura, pero a2db no permitirá escrituras incluso si el usuario tiene permisos de escritura.

El soporte de escritura está implementado en el núcleo pero aún no está expuesto a través de MCP. Planificado: permisos de escritura por conexión, habilitados explícitamente por el operador humano — no por el agente. Ver TODO.md.

Almacenamiento de credenciales

Las conexiones se guardan en ~/.config/a2db/connections/ como archivos TOML.

• Sintaxis ${DB_PASSWORD} — las referencias a variables de entorno se almacenan literalmente y se expanden solo en el momento de la conexión. Los secretos permanecen en tu entorno, no en el disco.

• Sin secretos en la salida de lista — list_connections muestra el proyecto/entorno/db y el tipo de base de datos, nunca DSNs o contraseñas

• Los archivos de conexión son locales a tu máquina y están fuera de cualquier repositorio

Alcance de despliegue

a2db actualmente se ejecuta como un servidor MCP stdio local. Hereda las variables de entorno del proceso que lo inicia (tu shell, Claude Code, Docker). Este es el modelo estándar para servidores MCP locales — el mismo enfoque utilizado por DBHub, Google Toolbox y otros.

Planificado: transporte HTTP remoto con OAuth 2.1 según la especificación MCP. Por ahora, si se ejecuta en Docker, inyecta secretos a través de variables de entorno en tiempo de ejecución del contenedor.

Comparativa

Cuándo usar qué:

• a2db — consultas por lotes multi-DB con salida limpia, diseño centrado en el agente, configuración rápida

• DBHub — herramientas personalizadas vía configuración TOML, interfaz de banco de trabajo web

• Google Toolbox — ecosistema GCP, integración IAM, más de 40 fuentes

• PGMCP — lenguaje natural a SQL para PostgreSQL (requiere clave OpenAI)

• Supabase MCP — gestión completa de la plataforma Supabase (funciones edge, ramificación, almacenamiento)

Configuración por entorno

Local (macOS / Linux)

pip install a2db

# CLI
a2db login -p myapp -e dev -d main 'postgresql://user:pass@localhost/mydb'

# Or add as MCP server (see Quick Start)

Docker

FROM python:3.12-slim
RUN pip install a2db
CMD ["a2db-mcp", "--register", "myapp/prod/main", "postgresql://user:${DB_PASSWORD}@host/mydb"]

docker run -e DB_PASSWORD=secret -i my-a2db-image

Los secretos se inyectan como variables de entorno en tiempo de ejecución — nunca se incluyen en la imagen.

CI / Automatización

pip install a2db

# Pre-configured — no login needed
a2db-mcp --register myapp/ci/main "postgresql://ci_user:${CI_DB_PASSWORD}@db-host/mydb"

# Or use CLI directly
a2db login -p myapp -e ci -d main "postgresql://ci_user:${CI_DB_PASSWORD}@db-host/mydb"
a2db query -p myapp -e ci -d main "SELECT COUNT(*) FROM migrations"

Desarrollo

make bootstrap   # Install deps + hooks
make check       # Lint + test + security (full gate)
make test        # Tests with coverage (90% minimum)
make lint        # Lint only (never modifies files)
make fix         # Auto-fix + lint

Licencia

Apache 2.0