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, plus clean removal with DROP EXTENSION and correct handling by pg_dump --clean.

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 165 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 Using the Seed Catalog for what to do next.

Continue to Testing Your Installation.