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"

Warum a2db?

Die meisten Datenbank-MCP-Server zwingen Sie dazu, eine Abfrage nach der anderen auszuführen, Verbindungsdetails bei jedem Aufruf zu wiederholen und Ergebnisse doppelt kodiert in JSON-Strings zurückzugeben. a2db behebt all das:

• Vorab konfigurierte Verbindungen — definieren Sie Datenbanken in .mcp.json mit --register, der Agent kann sofort abfragen

• Batch-Abfragen — führen Sie mehrere benannte Abfragen in einem einzigen Tool-Aufruf aus

• Standardverbindung — legen Sie die Verbindung einmal fest und verwenden Sie sie für alle Abfragen in einem Batch

• Saubere Ausgabe — strukturierter JSON-Umschlag mit kompakten TSV-Daten und Timing pro Abfrage (siehe warum TSV?)

• Erzwungener Schreibschutz — SQLGlot AST-Parsing blockiert alle Schreiboperationen

• Alle Treiber gebündelt — pip install a2db und Sie sind fertig

• Geheimnisse bleiben in der Umgebung — ${DB_PASSWORD} in DSNs wird erst zum Zeitpunkt der Verbindung erweitert

Unterstützte Datenbanken

Schnellstart

pip install a2db

Als MCP-Server (empfohlen)

Claude Code (mit vorab konfigurierter Verbindung):

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

Claude Code (minimal — Agent ruft bei Bedarf login auf):

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

Claude Desktop / Cursor / jeder MCP-Client (.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"
      }
    }
  }
}

Mehrere Datenbanken:

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

--register registriert Verbindungen beim Serverstart vor — der Agent kann sofort abfragen. Passwörter verwenden die ${ENV_VAR}-Syntax und werden zum Zeitpunkt der Verbindung erweitert, niemals im Klartext gespeichert.

Als 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

MCP-Tools

execute — das Kern-Tool

Benanntes Dictionary mit Standardverbindung (bevorzugt):

{
  "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"}
  }
}

Listenformat (automatisch benannt 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"}
  ]
}

Antwort (TSV-Format — Standard):

{
  "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
  }
}

Keine ::text-Casts erforderlich — Ganzzahlen, Gleitkommazahlen, Zeitstempel, Arrays, NULLs funktionieren alle nativ.

Fehlerkontext

Wenn eine Abfrage mit einem Spaltenfehler fehlschlägt, reichert a2db die Nachricht an:

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

Warum TSV?

LLM-Kontextfenster sind teuer. JSON-Zeilendaten sind wortreich — jede Zeile wiederholt jeden Spaltennamen, fügt geschweifte Klammern, Kommas und Anführungszeichen hinzu. TSV ist ein flaches Raster: eine Kopfzeile, dann nur durch Tabs getrennte Werte.

Für einen Ergebnissatz mit 100 Zeilen und 5 Spalten verbraucht TSV typischerweise 40-60% weniger Token als das JSON-Zeilenformat. Der strukturierte JSON-Umschlag liefert Ihnen weiterhin Metadaten (Zeilenanzahl, Kürzungsstatus) — nur die Zeilennutzlast ist TSV.

Setzen Sie format="json", wenn Sie eine vollständig strukturierte Ausgabe mit Spaltennamen in jeder Zeile benötigen.

Sicherheit

Erzwungener Schreibschutz

Jede Abfrage wird vor der Ausführung von SQLGlot geparst:

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

• Umgehungssicher: Angriffe mit mehreren Anweisungen und in Kommentaren verpackte Schreibvorgänge werden auf AST-Ebene erkannt, nicht nur durch Schlüsselwortabgleich

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

Dies ist eine tiefgestaffelte Verteidigung — Sie sollten zusätzlich einen schreibgeschützten Datenbankbenutzer verwenden, aber a2db lässt keine Schreibvorgänge durch, selbst wenn der Benutzer Schreibrechte hat.

Schreibunterstützung ist im Kern implementiert, aber noch nicht über MCP verfügbar. Geplant: Schreibrechte pro Verbindung, explizit vom menschlichen Bediener aktiviert — nicht vom Agenten. Siehe TODO.md.

Speicherung von Anmeldedaten

Verbindungen werden in ~/.config/a2db/connections/ als TOML-Dateien gespeichert.

• ${DB_PASSWORD}-Syntax — Umgebungsvariablen-Referenzen werden wörtlich gespeichert und erst zum Zeitpunkt der Verbindung erweitert. Geheimnisse bleiben in Ihrer Umgebung, nicht auf der Festplatte.

• Keine Geheimnisse in der Listen-Ausgabe — list_connections zeigt Projekt/Umgebung/DB und Datenbanktyp, niemals DSNs oder Passwörter

• Verbindungsdateien sind lokal auf Ihrem Computer und außerhalb jedes Repositorys

Bereitstellungsumfang

a2db läuft derzeit als lokaler stdio-MCP-Server. Er erbt Umgebungsvariablen von dem Prozess, der ihn startet (Ihre Shell, Claude Code, Docker). Dies ist das Standardmodell für lokale MCP-Server — der gleiche Ansatz, der von DBHub, Google Toolbox und anderen verwendet wird.

Geplant: Remote-HTTP-Transport mit OAuth 2.1 gemäß MCP-Spezifikation. Wenn Sie derzeit in Docker ausführen, injizieren Sie Geheimnisse über Umgebungsvariablen zur Laufzeit des Containers.

Vergleich

Wann was verwenden:

• a2db — Multi-DB-Batch-Abfragen mit sauberer Ausgabe, Agent-First-Design, schnelle Einrichtung

• DBHub — benutzerdefinierte Tools über TOML-Konfig, Web-Workbench-UI

• Google Toolbox — GCP-Ökosystem, IAM-Integration, 40+ Quellen

• PGMCP — natürliche Sprache zu SQL für PostgreSQL (erfordert OpenAI-Key)

• Supabase MCP — vollständige Supabase-Plattformverwaltung (Edge-Funktionen, Branching, Speicher)

Einrichtung nach Umgebung

Lokal (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

Geheimnisse werden zur Laufzeit als Umgebungsvariablen injiziert — niemals in das Image eingebettet.

CI / Automatisierung

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"

Entwicklung

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

Lizenz

Apache 2.0