Welcome to pg_health_framework¶

pg_health_framework is a health-check data-collection framework for PostgreSQL — and, optionally, for PostgreSQL servers running pgEdge's Spock extension for multi-master replication. It gives your database a built-in, queryable repository of health checks: connection limits, long-running queries, vacuum and wraparound risk, index health, replication lag, security posture, and much more. You install it once, and from then on everything — running checks, judging the results, and reading them back — happens as ordinary SQL, inside your own database.

It installs either as a real PostgreSQL extension, or as a plain SQL script for environments where installing extensions isn't possible (some managed cloud databases restrict this). Both paths run exactly the same SQL and behave identically — see Installing pg_health_framework.

The idea in one sentence¶

A check collects a single piece of data about your server — say, how many superuser accounts exist — and a separate, generic layer decides afterwards whether that number is a problem. The check itself never makes that judgment call.

This separation is the framework's central design decision, and it is worth understanding before anything else:

Collection is a check running and recording exactly what it observed — a number, a true/false answer, or a structured breakdown. Nothing here is graded as good or bad.
Evaluation is a separate step that compares what was collected against a threshold (a configured "this is fine up to here, concerning past here, critical past here" rule) and produces a severity — ok, info, warning, or critical.

Because these two steps are independent, the same collected data can be judged differently in different places (a stricter threshold for your production suite than for a development one, say), and a brand new check can start collecting real data immediately — you can add the judgement rule later, or never, if you just want the raw numbers.

What you get out of the box¶

pg_health_framework ships with:

165 built-in checks, organised into 15 categories — everything from "is SSL turned on" to "how far behind is my replica." See Using the Seed Catalog for the full list.
41 default thresholds for the checks where a sensible default makes sense, carried over from a well-established upstream project (see the Licence book for attribution).
Ready-made suites — named, ordered lists of checks you can run with a single command, with no setup required.
A generic dispatch engine that runs whatever checks a suite contains — adding your own check is enough to make it run; no part of the framework itself needs to change.

Who this is for¶

You do not need to be a PostgreSQL expert to use this framework, but a basic working knowledge of PostgreSQL — connecting with psql, running a SELECT, what an extension is — is assumed throughout this site. Where a PostgreSQL concept or an acronym comes up that goes beyond that, it is explained the first time it appears, and every term also has an entry in the Glossary.

Reading this guide¶

This User Guide walks through the framework roughly in the order you would actually use it: install it, understand the concepts, run the built-in checks, understand how their results are judged, and then — only if you need it — extend it with your own checks. If you are extending the framework with your own checks in any depth, the dedicated Adding Your Own Checks book picks up where this guide's Creating Your Own Checks and Thresholds chapter leaves off, and the Reference Guide documents every function's exact parameters.

Continue to Installing pg_health_framework.