Skip to content

pg_health_framework Documentation

pg_health_framework is a PostgreSQL and pgEdge-Spock health-check data-collection framework, built by Pebble IT Solutions Pty Ltd in Australia. This is version 0.1.0.

In plain terms: pg_health_framework gives your PostgreSQL database a built-in repository of 165 health checks — connection limits, vacuum health, replication lag, index bloat, security posture, and much more — plus a way to run them on a schedule, judge the results against thresholds, and be told when something needs attention. Everything runs as ordinary SQL inside your own database; there is no separate agent or external service to operate.

If a term on this site is unfamiliar — an acronym, a PostgreSQL concept, a piece of jargon — check the Glossary. Every book on this site links to it the first time a tricky term comes up.

Where to start

If you are new to pg_health_framework, read the books in this order:

  1. User Guide — what pg_health_framework is, how it is put together, and how to install it, run it, and read its results. Start here.
  2. Reference Guide — the complete technical reference: every function and procedure, its parameters, and what it returns.
  3. Adding Your Own Checks — only needed if the built-in 165 checks don't cover something specific to your own systems, or you want your own variant of a built-in check.
  4. Events — only needed if you want to be notified automatically the moment a check's severity changes, rather than only when someone goes and looks.

The remaining book is reference material you can dip into at any time:

Book What it covers
Licence What you are allowed to do with pg_health_framework, in plain English and in full legal text — including the third-party project this one builds on.
Glossary Every acronym and technical term used across this site, explained.

How this site is organised

This site is arranged like a small library:

Book  (top tab, e.g. "User Guide")
 └── Chapter  (left-hand menu, e.g. "Installing pg_health_framework")
      └── Section  (right-hand "On this page" menu, e.g. "As a plain SQL script")
  • Pick a book from the tabs across the top of the page.
  • Pick a chapter from the menu on the left — this changes depending on which book you are in.
  • Use the "On this page" menu on the right to jump to a section within the current chapter.
  • Use the search box at the top of the page to find anything by keyword, across every book at once.

A quick one-sentence summary

You collect data with pghf.execute_check_run(), judge it against thresholds with pghf.evaluate_run(), and read the results with pghf.get_results_sql() — three separate steps, on whatever schedule you choose:

STAGE 1 — COLLECT               STAGE 2 — EVALUATE                STAGE 3 — REPORT
CALL pghf.execute_check_run()   CALL pghf.evaluate_run()          SELECT * FROM
  ──► pghf.runs                   ──► pghf.evaluations                pghf.get_results_sql(run_id)
  ──► pghf.raw_results            (raw data × thresholds
      (pure data, no judgment)     = a severity)

Collection and evaluation are deliberately separate: a check only ever records what it observed, never a verdict — that comes from a threshold, applied afterwards, generically, by a separate layer. Read the User Guide for the full explanation.

pg_health_framework is published and maintained by Pebble IT Solutions Pty Ltd, Australia. Source code and releases: gitlab.com/pebble-it/postgresql-health-framework. Licensed under the MIT Licence; its check-body SQL is adapted from pgEdge's pg-healthcheck project under the PostgreSQL Licence — see Third-Party Notices.