pg_vault_connect — Connect to PostgreSQL via HashiCorp Vault with Zero Static Passwords

What Does This Tool Do?

pg_vault_connect establishes a connection to PostgreSQL without any static passwords involved. Instead of storing credentials in environment variables or config files, the tool authenticates via AppRole with HashiCorp Vault, fetches dynamic credentials from the Database Secret Engine, and creates a connection pool. Each credential has a limited lifetime (lease TTL) and becomes invalid automatically upon expiration.

How Is It Called?

Step 1: Establish Multi-DB Connection

The MCP server supports multiple simultaneous connections. With pg_vault_connect, the manual connection step is replaced — the tool fetches credentials automatically from Vault:

Step 2: Claude CLI (Natural Language)

MCP Protocol (Programmatic)

The following output is representative of Vault E2E tests — the structure matches the real tool output format (Vault tests run separately with VAULT_ADDR):

What Happens Under the Hood?

This tool executes no SQL. Instead, it communicates via the Vault HTTP API:

1. AppRole Login — POST /v1/auth/approle/login with Role ID and Secret ID. Vault returns a client token.
2. Fetch Credentials — GET /v1/database/creds/{role} with the client token. Vault creates an on-the-fly PostgreSQL user with a limited lifetime.
3. Connection Pool — A pg.Pool is created with the dynamic username and password, and the connection is verified (SELECT 1).

Output in Detail

• status — connected or error
• profile — Name of the connection profile used
• vault_role — The Vault role that defines the PostgreSQL user (permissions, TTL)
• username — The dynamically generated PostgreSQL username (e.g., v-approle-pg-readon-x9k2m)
• lease_id — Vault's lease identifier for renewal or revocation
• lease_ttl — Remaining validity in seconds
• password — Always <redacted> in output — the password is only used internally

What Does the Test Suite Validate?

The test suite validates pg_vault_connect against a Vault instance at vault.example.com:8200 with a configured Database Secret Engine and a pg-readonly role:

Test Data Scenario

The test environment contains:

• Vault Server — HashiCorp Vault at vault.example.com:8200 with Database Secret Engine enabled
• AppRole — Configured Role ID and Secret ID for machine-to-machine auth
• pg-readonly Role — Vault database role with SELECT permissions and 1h TTL
• PostgreSQL — Target database where Vault is authorized to create dynamic users

Tests validate that:

1. The connection is established via a named Vault profile and returns status: connected
2. The response includes lease information (lease_id, lease_ttl > 0)
3. The password always appears as <redacted> in output — never in plaintext

Summary

pg_vault_connect eliminates static database passwords entirely. Every connection receives short-lived, automatically expiring credentials — a cornerstone of zero-trust architecture.

Combined with pg_vault_rotate (→ credential rotation) and pg_hba_analyze (→ authentication audit), it forms the core of the /pg-security workflow skill.