pgvault

pgvault is a wrapper around pgcli and vault.

It is a CLI tool designed to eliminate the friction of connecting to PostgresQL databases secured by HashiCorp Vault's dynamic credentials.

Instead of manually requesting temporary credentials from Vault, parsing the JSON output, and passing the username and password to a database client, pgvault handles the entire flow in a single command. It reads your database configuration, authenticates with Vault, extracts the dynamic credentials, and drops you into a pgcli session.

Prerequisites

1. Nix & Flakes: You need Nix installed on your system with Flakes enabled.
   • Recommended: We highly recommend installing Nix via the Determinate Systems Nix Installer. It is faster, more reliable than the official installer, and enables Flakes by default.
2. Vault Session: You must have the VAULT_ADDR environment variable exported in your terminal, and an active Vault session (run vault login before using this tool).

Configuration

pgvault uses a TOML file to manage your database profiles.

By default, the script looks for the configuration file at: ~/.config/pgvault/config.toml

(You can override this location by setting the PGVAULT_CONFIG environment variable).

Example config.toml

Create your configuration file and add your database profiles like this:

[my-db-prod]
vault_role_path = "database/creds/prod-role"
host = "prod.database.internal.com"
port = 5432
dbname = "postgres"

[analytics-db-dev]
vault_role_path = "database/creds/analytics-dev-role"
host = "dev.analytics.database.internal.com"
# If port is omitted, the script will safely default to 5432
dbname = "analytics_db"

Usage

You have two options for running pgvault: executing it temporarily, or installing it permanently to your Nix user profile.

Option 1: Temporary Execution (nix run)

You can run the script directly from this directory (or remotely from GitHub) without installing it permanently to your system's PATH.

# Run from a local clone
nix run . -- my-db-prod

# OR run directly from the remote repository
nix run git+https://codeberg.org/jasterv/pgvault -- my-db-prod

Option 2: Permanent Installation (nix profile add)

If you want to use pgvault as a native command-line utility day-to-day, install it to your Nix profile:

# Install from a local clone
nix profile add .

# OR install from the remote repository
nix profile add git+https://codeberg.org/jasterv/pgvault

Once installed, simply run:

pgvault my-db-prod

Under the Hood: pgcli

Once the Vault credentials are automatically fetched, pgvault connects to your database using pgcli (not standard psql).

pgcli is a modern, highly capable PostgresQL client that provides auto-completion and syntax highlighting directly in your terminal. If you are new to pgcli and want to learn about its features (like smart completion and multiline queries), check out the official pgcli documentation.

Why Nix?

This tool is packaged using Nix Flakes. We chose Nix for a few critical reasons:

1. Zero System Clutter: pgvault relies on vault, yq, jq, and pgcli. By using Nix, these dependencies are bundled directly into the script's execution environment. You do not need to install or manage these tools globally on your system.
2. Reproducibility: Nix guarantees that this script will run with the exact same dependency versions on any machine (Linux or macOS), eliminating "it works on my machine" issues.
3. Instant Setup: Anyone on your team can run this tool instantly without going through a multi-step installation guide for various package managers.