pg_vault_connect — PostgreSQL-Verbindung über HashiCorp Vault ohne statische Passwörter — Blog

Was macht dieses Tool?

pg_vault_connect stellt eine Verbindung zu PostgreSQL her, ohne dass statische Passwörter im Spiel sind. Statt Credentials in Umgebungsvariablen oder Config-Dateien zu hinterlegen, authentifiziert sich das Tool per AppRole bei HashiCorp Vault, bezieht dynamische Credentials aus der Database Secret Engine und baut damit einen Connection Pool auf. Jede Credential hat eine begrenzte Lebensdauer (Lease TTL) und wird nach Ablauf automatisch ungültig.

Wie wird es aufgerufen?

Schritt 1: Multi-DB-Verbindung herstellen

Der MCP-Server unterstützt mehrere gleichzeitige Verbindungen. Bei pg_vault_connect entfällt die manuelle Verbindung — das Tool bezieht die Credentials automatisch über Vault:

● ● ● Claude CLI — Verbindung

claude> Verbinde mit Profil "production-db"

▶ Calling tools...
→ pg_connect { "host": "localhost", "port": 5432, "database": "mcp_test", "user": "mcp_test" }

Verbindung hergestellt:

Status:     connected
Server:     PostgreSQL 17.4
Datenbank: mcp_test
User:       mcp_test

Schritt 2: Claude CLI (natürliche Sprache)

● ● ● Claude CLI — Vault-Verbindung

claude> Verbinde dich über Vault mit der Produktionsdatenbank

▶ Calling tools...
→ pg_vault_connect { "profile": "production" }

Verbindung über Vault hergestellt:

Status:      connected
Profil:      production
Vault-Rolle: pg-readonly
Username:    v-approle-pg-readon-x9k2m
Lease-ID:    database/creds/pg-readonly/abc123def456
Lease-TTL:   3600s
Passwort:    <redacted>

MCP Protocol (programmatisch)

Die folgende Ausgabe ist repräsentativ für die Vault E2E-Tests — die Struktur entspricht dem echten Tool-Output-Format (Vault-Tests laufen separat mit VAULT_ADDR):

● ● ● MCP Protocol — Vault-Verbindung

// Programmatic invocation via MCP SDK
const result = await client.callTool("pg_vault_connect", { "profile": "production" });

// Response:
{
"status": "connected",
"profile": "production",
"vault_role": "pg-readonly",
"username": "v-approle-pg-readon-x9k2m",
"lease_id": "database/creds/pg-readonly/abc123def456",
"lease_ttl": 3600,
"password": "<redacted>"
}

Was passiert unter der Haube?

Dieses Tool führt kein SQL aus. Stattdessen kommuniziert es über die Vault HTTP API:

AppRole-Login — POST /v1/auth/approle/login mit Role-ID und Secret-ID. Vault gibt ein Client-Token zurück.
Credentials abrufen — GET /v1/database/creds/{role} mit dem Client-Token. Vault erstellt on-the-fly einen PostgreSQL-User mit begrenzter Lebensdauer.
Connection Pool — Mit dem dynamischen Username und Passwort wird ein pg.Pool erstellt und die Verbindung verifiziert (SELECT 1).

Warum AppRole? AppRole ist Vaults Machine-to-Machine-Authentifizierung. Kein menschliches Login, kein Browser, kein OIDC-Flow — nur eine Role-ID (öffentlich) und eine Secret-ID (kurzlebig, einmal verwendbar). Perfekt für MCP-Server und CI/CD-Pipelines.

Ausgabe im Detail

status — connected oder error
profile — Name des verwendeten Verbindungsprofils
vault_role — Die Vault-Rolle, die den PostgreSQL-User definiert (Berechtigungen, TTL)
username — Der dynamisch erzeugte PostgreSQL-Benutzername (z.B. v-approle-pg-readon-x9k2m)
lease_id — Vaults Lease-Identifier zum Erneuern oder Widerrufen
lease_ttl — Verbleibende Gültigkeitsdauer in Sekunden
password — Immer <redacted> in der Ausgabe — das Passwort wird nur intern verwendet

Sicherheitshinweis: Das Passwort wird niemals in Logs, CLI-Ausgaben oder MCP-Responses angezeigt. Der Connection Pool speichert es nur im Arbeitsspeicher. Nach Lease-Ablauf ist das Passwort wertlos.

Was testet die Testsuite?

Die Testsuite validiert pg_vault_connect gegen eine Vault-Instanz auf vault.example.com:8200 mit konfigurierter Database Secret Engine und einer pg-readonly-Rolle:

● ● ● vitest run — Testsuite

✓ pg_vault_connect > connects via Vault profile
✓ pg_vault_connect > returns lease info with TTL
✓ pg_vault_connect > password is redacted in output

Test Files 1 passed (1)
Tests 3 passed (3)
Duration 845ms

Testdaten-Szenario

Die Testumgebung enthält:

Vault Server — HashiCorp Vault auf vault.example.com:8200 mit aktivierter Database Secret Engine
AppRole — Konfigurierte Role-ID und Secret-ID für Machine-to-Machine-Auth
pg-readonly Rolle — Vault-Datenbank-Rolle mit SELECT-Berechtigungen und 1h TTL
PostgreSQL — Zieldatenbank, in der Vault dynamische User anlegen darf

Die Tests validieren, dass:

Die Verbindung über ein benanntes Vault-Profil hergestellt wird und status: connected zurückgibt
Die Antwort Lease-Informationen enthält (lease_id, lease_ttl > 0)
Das Passwort in der Ausgabe immer als <redacted> erscheint — nicht im Klartext

Zusammenfassung

Vault API

Datenquelle

Ausgabefelder

Tests

zero-trust

Typ

pg_vault_connect eliminiert statische Datenbank-Passwörter vollständig. Jede Verbindung erhält kurzlebige, automatisch ablaufende Credentials — ein Grundpfeiler der Zero-Trust-Architektur.

In Kombination mit pg_vault_rotate (→ Credential-Rotation) und pg_hba_analyze (→ Authentifizierungs-Audit) bildet es den Kern des /pg-security Workflow-Skills.

pg_vault_connect — PostgreSQL-Verbindung über HashiCorp Vault ohne statische Passwörter