Docs / Install Guide

Install PGVitals Agent

Prerequisites

PostgreSQL 12+ with pg_stat_statements extension enabled
A PGVitals account and API key (get one at signup)

1. Enable pg_stat_statements

Add to your postgresql.conf or run:

sqlCREATE EXTENSION IF NOT EXISTS pg_stat_statements;

On RDS: modify the parameter group to set shared_preload_libraries = pg_stat_statements and reboot.

Verify it's working:

sqlSELECT count(*) FROM pg_stat_statements;

If this returns a number (even 0), you're good. If you get relation "pg_stat_statements" does not exist, ensure shared_preload_libraries includes pg_stat_statements in your postgresql.conf and restart Postgres.

2. Create a read-only database user (recommended)

The agent only needs read access to PostgreSQL statistics views. We strongly recommend creating a dedicated user with minimal privileges:

sql-- Create a dedicated read-only user for PGVitals
CREATE USER pgvitals WITH PASSWORD 'a_strong_password_here';

-- Grant access to connect
GRANT CONNECT ON DATABASE your_database TO pgvitals;

-- Grant access to pg_stat_statements
GRANT SELECT ON pg_stat_statements TO pgvitals;

-- Grant access to schema for table/index stats
GRANT USAGE ON SCHEMA public TO pgvitals;

Then use this user in your connection string:

bashPGVITALS_DATABASE_URL="postgres://pgvitals:a_strong_password_here@host:5432/your_database"

Security best practice

The agent never writes to your database. It only reads from pg_stat_statements, pg_stat_user_tables, and pg_stat_user_indexes. Using a read-only user ensures the agent cannot modify any data even if compromised.

3. Install the agent

The agent is open-source: github.com/call-stack/pgvital-agent

Docker (recommended)

bashdocker run -d \
  -e PGVITALS_DATABASE_URL="postgres://pgvitals:your_password@host:5432/dbname" \
  -e PGVITALS_API_KEY="pgp_live_your_key_here" \
  --name pgvitals-agent \
  kalpitpant/pgvital-agent:latest

4. Configure and run

bashexport PGVITALS_DATABASE_URL="postgres://pgvitals:your_password@host:5432/dbname"
export PGVITALS_API_KEY="pgp_live_your_key_here"

# Optional
export PGVITALS_INTERVAL="5m"        # Collection interval (default: 5m)
export PGVITALS_HOSTNAME="prod-db-01" # Label for this instance

pgvitals-agent

5. Verify

After starting the agent, check your dashboard — the instance should appear within 1 minute. You'll receive a welcome email to confirm everything is working, then a weekly digest every Monday at 9:00 AM UTC.

Environment variables

Variable	Required	Description
PGVITALS_DATABASE_URL	Yes	Postgres connection string
PGVITALS_API_KEY	Yes	Your org API key
PGVITALS_SERVER_URL	No	PGVitals server URL (default: https://api.pgvitals.kafal.studio)
PGVITALS_INTERVAL	No	Collection interval (default: 5m, min: 1m, max: 1h)
PGVITALS_HOSTNAME	No	Human-readable label for this instance