What is pgpulse?
pgpulse is a PostgreSQL health intelligence platform. It connects to your Postgres instance, collects deep diagnostic data on a continuous schedule, and distills everything into a single 0–100 score called the Pulse — plus actionable signals that tell you exactly what is wrong and why.
No DBA expertise required. No Grafana configuration. No guesswork.
The problem with traditional monitoring
Most database monitoring tools give you dashboards full of numbers — CPU %, connections, query count — but leave you to figure out what those numbers mean for your database's health.
Is 80% CPU utilization bad right now? It depends on your workload, your Postgres version, whether you're running Supabase burstable compute, and a dozen other factors. Traditional tools hand you the raw signal and walk away.
pgpulse doesn't do that. It watches 11 health domains simultaneously, applies thresholds tuned for Postgres specifically, and surfaces only what matters: a health score, the domains driving it down, and the queries or conditions responsible.
The Pulse score
The Pulse is a composite 0–100 number computed from your instance every 30 seconds.
| Score | What it means |
|---|---|
| 90–100 | Healthy — all domains within normal range |
| 60–89 | Warning — one or more domains are degrading |
| 1–59 | Critical — significant issues requiring attention |
| 0 | Gate fired — a hard failure condition is active (e.g. XID wraparound risk, storage corruption) |
A score of 0 is not "very bad" — it means a gate has triggered. Gates are unconditional overrides for conditions so severe that no weighted average makes sense: transaction ID wraparound proximity, storage corruption, replication slot stalls about to exhaust disk. When a gate is active, everything else is secondary.
11 health domains
The Pulse is a weighted average of 11 domains, each covering a distinct failure mode in Postgres. Weights reflect how catastrophic and irreversible each failure is — not how often it occurs.
| Domain | Weight | What it tracks |
|---|---|---|
| Freeze Risk | 15 | XID age, wraparound proximity — Postgres shuts down at the 2 billion limit |
| Replication & Recovery | 14 | WAL archive gaps, slot stalls, replica lag — silent data-loss risks on failover |
| Connection Pressure | 12 | Active / idle connections vs. max_connections — exhaustion is a hard wall, no graceful degradation |
| Lock Contention | 11 | Long-lived blockers, ACCESS EXCLUSIVE waits, deadlock chains |
| Bloat | 10 | Dead tuple accumulation inflating table and index sizes, defeating autovacuum |
| Vacuum Engine | 9 | Autovacuum health — when it's starved, freeze debt and bloat compound silently |
| Query Throughput | 8 | Planner misestimates, sequential scans, missing indexes — where user-visible latency originates |
| WAL Pipeline | 7 | Checkpoint throughput and write I/O pressure |
| Disk Vitals | 7 | Filesystem usage, I/O latency — the physical layer everything else depends on |
| Object Integrity | 4 | Invalid indexes, sequence exhaustion, unvalidated constraints, checksum failures |
| Memory Fit | 3 | Buffer pool hit rates, work_mem spills |
How it works end-to-end
Your Postgres instance
│
│ SQL queries against pg_stat_* views, pg_locks,
│ pg_replication_slots, pg_stat_user_tables, etc.
▼
pgpulse collector
(lightweight Go binary or agentless cloud connection)
│
│ Structured JSON payloads over HTTPS
│ Buffered locally if the API is temporarily unreachable
▼
pgpulse API
│
│ Authenticates, validates, stores in TimescaleDB
▼
Scoring engine ──── runs every 30 seconds
│
│ Applies thresholds, computes domain scores,
│ checks gates, writes Pulse to dashboard
▼
Your dashboard
Pulse score · domain breakdown · query insights · alerts
The collector runs either as a self-hosted binary on your infrastructure, or in agentless mode where pgpulse connects directly to your database using credentials you provide. Either way, the collector only runs read-only queries — it never writes to your database.
What you see in the dashboard
| View | What it shows |
|---|---|
| Pulse score | Your instance's 0–100 health number, updated every 30 seconds |
| Domain breakdown | Which of the 11 domains are degraded and by how much |
| Golden Signals | CPU, memory, connections, and I/O trends over time |
| Query Insights | Slow queries, sequential scans, lock contention, index recommendations |
| Database Advisory | Specific, actionable recommendations: vacuum settings, missing indexes, connection pool tuning |
| Alerts | Threshold-based notifications via Slack, Email, or webhook |
Who it's for
pgpulse is built for developers and small engineering teams running Supabase or standalone Postgres who want to understand their database health without hiring a DBA or spending hours configuring observability infrastructure.
It's especially useful if you:
- Run on Supabase and want visibility into burstable CPU, PgBouncer/Supavisor connection patterns, and vacuum health
- Have a production database and want early warning before an incident
- Are seeing slow API responses and want to know if the database is the cause
- Are approaching launch and want to validate your database can handle real load