Getting Started withpgSentinel

Quick setup guide to get pgSentinel running in minutes. Professional pgbalancer monitoring with real-time metrics and analytics.

5-minute setup
Docker ready
Production ready

Setup Steps

Follow these steps to get pgSentinel running

1

Prerequisites

System requirements and dependencies

System Requirements

  • Docker and Docker Compose installed
  • PostgreSQL 12+ with pg_stat_statements extension
  • 4GB RAM minimum (8GB recommended)
  • 2GB disk space for logs and data

PostgreSQL Setup

-- Enable required extensions
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS pg_stat_kcache;
CREATE EXTENSION IF NOT EXISTS pg_qualstats;
CREATE EXTENSION IF NOT EXISTS pg_buffercache;
2

Installation

Clone repository and configure environment

Clone Repository

git clone https://github.com/pgelephant/pgsentinel.git
cd pgsentinel

Configure Environment

cp env.template .env
# Edit .env with your PostgreSQL connection details

Environment Variables

Required configuration:
DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
REDIS_URL=redis://localhost:6379
PROMETHEUS_PORT=9090
GRAFANA_PORT=3001
3

Start Services

Launch the complete monitoring stack

Start All Services

docker-compose up -d

Verify Services

docker-compose ps
# All services should show 'Up' status

Check Logs

docker-compose logs -f backend
docker-compose logs -f frontend
4

Access Dashboard

Open the monitoring dashboard and verify setup

Access Points

Main Dashboard
http://localhost:3000
Real-time monitoring interface
API Documentation
http://localhost:8000/docs
Interactive API documentation
Grafana
http://localhost:3001
admin/admin (default login)
Prometheus
http://localhost:9090
Metrics collection and queries
5

Configuration

Customize settings and connect to your PostgreSQL

Database Connection

Update .env file with your PostgreSQL details:
DATABASE_URL=postgresql://username:password@host:port/database
Replace with your actual connection details

Restart Services

docker-compose restart backend
# Backend will reconnect to your database

Verify Connection

Check the dashboard for:
  • Database connection status
  • Real-time metrics appearing
  • pg_stat_insights data loading

Quick Verification

Verify everything is working correctly

Dashboard Check

  • Open http://localhost:3000
  • Verify real-time metrics are updating
  • Check WebSocket connection (green indicator)
  • Navigate to /insights for pg_stat_insights

Grafana Check

  • Open http://localhost:3001
  • Login with admin/admin
  • Check pgSentinel dashboards are loaded
  • Verify data is flowing from Prometheus

Troubleshooting

Common issues and solutions

Services not starting

Check Docker is running and ports are available

$ docker-compose ps
$ docker-compose logs

Database connection failed

Verify DATABASE_URL in .env file and PostgreSQL is accessible

$ docker-compose logs backend
$ psql $DATABASE_URL

No metrics appearing

Ensure pg_stat_statements is enabled and PostgreSQL is restarted

$ SELECT * FROM pg_stat_statements LIMIT 1;
$ docker-compose restart backend

Grafana login issues

Default credentials are admin/admin, check container logs

$ docker-compose logs grafana
$ docker-compose exec grafana grafana-cli admin reset-admin-password admin

Next Steps

Now that pgSentinel is running, explore the advanced features and customization options.

Configuration

Customize settings and environment variables

Dashboard Guide

Learn to use the monitoring interface effectively

API Reference

Integrate with your applications using the REST API