Skip to content

Installing pg_health_framework

There are two ways to install pg_health_framework. Both run exactly the same SQL underneath — the only difference is whether you use PostgreSQL's own extension machinery on top.

This is the normal path on a server where you can install PostgreSQL extensions — your own server, a virtual machine, or a cloud database that permits custom extensions.

cd pg_health_framework
make install        # requires pg_config on PATH
psql -d yourdb -c "CREATE EXTENSION pg_health_framework;"

pg_config is a small PostgreSQL utility that reports where your server expects extension files to be installed — make install uses it to copy the framework's files into the right place. If it isn't on your PATH, install your PostgreSQL server's development package first (on Debian/Ubuntu, this is usually postgresql-server-dev-<version>).

Installing this way gives you PostgreSQL's own dependency tracking and clean removal with DROP EXTENSION.

Known limitation: logical dump/restore (open question)

pg_dump records only the CREATE EXTENSION statement for an extension: PostgreSQL never dumps the contents of an extension's tables unless the extension marks them for it (pg_extension_config_dump()), and this extension currently marks none. A restored database therefore has the schema and a freshly reseeded built-in catalog, but none of your own rows — custom checks and thresholds, suite edits, blackouts, notifications, run hooks — and none of the execution history (runs, raw results, evaluations, alert status, the notification outbox). A physical restore (pg_basebackup, snapshots) is unaffected, and so is the plain-SQL install path below, whose tables dump normally. Until this is resolved (marking the tables is the fix, and needs a migration plan for existing installs), keep a script of your own registrations to re-run after a logical restore, or use the plain-SQL install where dump fidelity matters.

As a plain SQL script (no extension machinery)

Some managed cloud PostgreSQL services (see the note on cloud restrictions below) don't allow installing your own extensions. For those, build and load a single plain SQL file instead:

make plain-sql       # builds pg_health_framework--0.1.0.sql from sql/*.sql
psql -d yourdb -f pg_health_framework--0.1.0.sql

This runs the exact same SQL as CREATE EXTENSION — every table, function, and the built-in check catalog — just without PostgreSQL's extension bookkeeping layered on top. Removing it later means dropping the pghf schema yourself, since there's no DROP EXTENSION to do it for you.

Either way, everything lives in one schema

Both installation paths put every object — tables, functions, the check catalog — into a single PostgreSQL schema called pghf. You never need to worry about name clashes with your own tables and functions, and every example on this site refers to objects with their full pghf. prefix for that reason.

What happens automatically at install time

At the end of either install path, the framework seeds itself: it registers its own built-in namespace, all 15 categories, all 175 checks, one or two ready-to-run suites, and the default thresholds that come with it. You don't need to run anything else before trying it out — see Running Checks End to End for what to do next.

Continue to Testing Your Installation.