pg_vault_rotate — Rotate Database Credentials Without Downtime

What Does This Tool Do?

pg_vault_rotate rotates the active database credentials of an existing Vault connection. It revokes the old lease in Vault, fetches fresh credentials from the Database Secret Engine, and automatically rebuilds the connection pool with the new user. Since this terminates active connections, the tool requires explicit confirmation (confirm: true).

How Is It Called?

Step 1: Establish Vault Connection

Before credentials can be rotated, a Vault connection must exist. The MCP server supports multiple simultaneous connections:

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?

Like pg_vault_connect, this tool executes no SQL. The entire workflow consists of Vault API calls and pool management:

1. Revoke Lease — PUT /v1/sys/leases/revoke with the active lease ID. Vault deletes the dynamic PostgreSQL user immediately.
2. Fetch New Credentials — GET /v1/database/creds/{role}. Vault creates a new dynamic user.
3. Disconnect Pool — pool.end() terminates all active connections in the old pool.
4. Rebuild Pool — new Pool() with the new username and password. Connection verified with SELECT 1.

Output in Detail

• rotated — true if rotation succeeded
• old_lease — Status of the old lease (revoked)
• new_username — The freshly generated PostgreSQL username
• new_lease_ttl — Validity of the new credentials in seconds
• pool_reconnected — true if the new pool was successfully verified

What Does the Test Suite Validate?

The test suite validates pg_vault_rotate with an active Vault lease from pg_vault_connect:

Test Data Scenario

The test environment requires an existing Vault connection:

• Active Vault Lease — Established by a prior pg_vault_connect call
• Database Secret Engine — Vault role pg-readonly with dynamic user creation
• PostgreSQL — Target database with Vault-managed users

Tests validate that:

1. Without confirm: true, rotation is rejected with a clear error message — no accidental rotations
2. With confirm: true, a new username is generated, the old lease has status revoked, and the pool is reconnected

Summary

pg_vault_rotate is the emergency tool for compromised credentials and the routine tool for planned rotations. Combined with pg_vault_connect, it provides a complete credential lifecycle without static passwords.

Together with pg_vault_connect (→ initial connection) and pg_hba_analyze (→ authentication audit), it belongs to the /pg-security workflow skill.