DocumentationpgSentinel Documentation

Getting Started with pgSentinel

Prerequisites

Spin up pgSentinel with Docker, connect to pgBouncer, and start visualising pool metrics using the built-in dashboards.

  • pgBouncer 1.18+ with admin console enabled
  • PostgreSQL 14+ for metrics storage (optional external DB)
  • Docker or Kubernetes runtime for container deployment
  • Prometheus (optional) for long-term metric retention

Step 1 · Launch pgSentinel

Run the official container image or helm chart.

Docker compose

docker-compose.yml

version: '3.9'
services:
  pgsentinel:
    image: ghcr.io/pgelephant/pgsentinel:latest
    ports:
      - '8080:8080'
    environment:
      - PGSENTINEL_PGBOUNCER_DSN=postgres://admin:secret@pgbouncer:6432/pgbouncer
      - PGSENTINEL_STORAGE_DSN=postgres://pgsentinel:pass@postgres:5432/pgsentinel
      - PGSENTINEL_PROMETHEUS_EXPORT=true

Kubernetes (Helm)

Install chart

helm repo add pgelephant https://charts.pgelephant.com
helm install pgsentinel pgelephant/pgsentinel \
  --set pgbouncer.dsn=postgres://admin:secret@pgbouncer:6432/pgbouncer \
  --set storage.dsn=postgres://pgsentinel:pass@postgres:5432/pgsentinel

Step 2 · Connect to pgBouncer & PostgreSQL

Provide connection strings for pgBouncer admin console and the metrics store.

pgBouncer credentials

pgbouncer.ini

[pgbouncer]
listen_port = 6432
admin_users = admin
stats_users = admin

[databases]
pgbouncer = host=postgres port=5432 dbname=pgbouncer user=admin password=secret

Metrics schema

Create pgSentinel role

CREATE ROLE pgsentinel WITH LOGIN PASSWORD 'pass';
CREATE DATABASE pgsentinel OWNER pgsentinel;
GRANT ALL PRIVILEGES ON DATABASE pgsentinel TO pgsentinel;

Step 3 · Enable Prometheus/Grafana

Expose metrics via /metrics and import the starter Grafana dashboard.

Prometheus scrape config

prometheus.yml

scrape_configs:
  - job_name: 'pgsentinel'
    static_configs:
      - targets: ['pgsentinel:8080']

Grafana import

Dashboard provisioning

curl -L https://raw.githubusercontent.com/pgElephant/pgsentinel/main/grafana/pgsentinel.json \
  -o /var/lib/grafana/dashboards/pgsentinel.json

Next Steps

PreviousTroubleshooting
NextConfiguration Reference