DocumentationpgSentinel Documentation

Configuration Reference

Required Services

pgSentinel needs read access to pgBouncer's admin console and a PostgreSQL database for persistent metrics. Provide DSNs via environment variables or Helm chart values.

docker-compose

services:
  pgsentinel:
    image: ghcr.io/pgelephant/pgsentinel:latest
    environment:
      PGSENTINEL_PGBOUNCER_DSN: postgres://admin:secret@pgbouncer:6432/pgbouncer
      PGSENTINEL_STORAGE_DSN: postgres://pgsentinel:pass@postgres:5432/pgsentinel
      PGSENTINEL_PROMETHEUS_EXPORT: 'true'
      PGSENTINEL_ADMIN_PASSWORD: changeme
      PGSENTINEL_JWT_SECRET: supersecret
    ports:
      - '8080:8080'

Create metrics database

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

Environment Variables

Grouped variables below can be injected with Docker, systemd units, or Kubernetes secrets. All secrets should be stored in a vault or encrypted store.

Core Services

  • PGSENTINEL_PGBOUNCER_DSN · required
    Admin DSN for pgBouncer (postgres URI including pooler port).
  • PGSENTINEL_STORAGE_DSN · required
    PostgreSQL DSN for metrics/time-series storage.
  • PGSENTINEL_PROMETHEUS_EXPORT · optional
    Enable `/metrics` endpoint (true|false).

Authentication & Security

  • PGSENTINEL_ADMIN_PASSWORD · required
    Initial admin password for the web UI.
  • PGSENTINEL_JWT_SECRET · required
    Secret used to sign API tokens.
  • PGSENTINEL_DISABLE_SIGNUP · optional
    Disallow new UI accounts (true|false).

Retention & Sampling

  • PGSENTINEL_METRICS_RETENTION_DAYS · optional
    Historical data retention window.
  • PGSENTINEL_SCRAPE_INTERVAL · optional
    Frequency for pgBouncer polling (e.g. 5s).
  • PGSENTINEL_ALERT_INTERVAL · optional
    How often alert rules evaluate (e.g. 30s).

Security Controls

Web UI hardening

  • Set PGSENTINEL_DISABLE_SIGNUP=true and create accounts via CLI or admin API.
  • Run behind a TLS-enabled reverse proxy (Traefik, Nginx) with basic auth or SSO.
  • Rotate PGSENTINEL_JWT_SECRET regularly and invalidate tokens via the admin panel.

Network & secrets

  • Use Kubernetes secrets / Docker secrets to mount DSNs instead of plain env vars where possible.
  • Restrict pgBouncer admin console to the pgSentinel network CIDR.
  • Limit database role privileges to INSERT/SELECT/DELETE on pgSentinel schemas.

Observability & Integrations

Prometheus & Grafana

  • Expose `/metrics` by setting PGSENTINEL_PROMETHEUS_EXPORT=true.
  • Scrape the endpoint every 15s and import the official Grafana dashboard from the docs.
  • Use recording rules for pool saturation and queue depth.

Alerting

  • Configure PGSENTINEL_ALERT_WEBHOOK for Slack/Teams notifications.
  • Set PGSENTINEL_ALERT_THRESHOLD_QUEUE and PGSENTINEL_ALERT_THRESHOLD_LATENCY to match SLAs.
  • Integrate with PagerDuty via the REST API's incident endpoints.
PreviousGetting Started
NextMetrics Catalog