Skip to content

Passing In Extra Input

Every check shares one signature — a single run-ID parameter — so there's no room for extra parameters of your own the way an ordinary function call would allow. Instead, use the framework's run-configuration table, which the collection engine already populates from its own optional parameters (the target PostgreSQL version, and the lists of tables to check with amcheck or pg_visibility) before it starts running any checks.

  • Read it back inside your own check function with the framework's ready-made helper functions for pulling a specific key back out as an integer or a text array. See the built-in pg_upgrade-readiness checks (which read the target-version key) or the visibility-map checks (which read the pg_visibility table list) for real examples of the pattern.
  • If your own parameter doesn't map onto one of the collection engine's existing optional arguments, insert your own row into the run-configuration table yourself, before calling the collection engine — this table isn't locked down the way the check catalog is, since it's scratch data scoped to one run, not part of the catalog.
  • If missing configuration simply means the check doesn't apply, return a skipped result with a clear explanation (the same pattern the pg_upgrade-readiness checks use) rather than raising an error or guessing at a value.

Checking for an extension, version-aware

The collection engine also writes every installed extension's name and version into the run-configuration table automatically, under its own key, at the start of every run — no setup needed on your part. Two more ready-made helper functions read it back:

  • One returns the installed version string for a named extension, or nothing if it isn't installed at all.
  • The other is a plain true/false wrapper around the first — "is this extension present at all," with no need to check for a nothing-result yourself.

This makes a version-aware dependency check a single call instead of a hand-rolled query:

IF pghf._run_extension_version(p_run_id, 'vector') IS NULL THEN
    RETURN ROW('SKIPPED', NULL, 'pgvector not installed')::pghf.check_result;
ELSIF pghf._run_extension_version(p_run_id, 'vector') < '0.7.0' THEN
    RETURN ROW('SKIPPED', NULL, 'requires pgvector 0.7.0+')::pghf.check_result;
END IF;

This is a self-evaluation aid, not an engine-enforced gate like the version/topology metadata in Declaring a Version or Topology Requirement — your check still tests for and skips itself for a missing or too-old extension; this just makes that test cheaper to write than reading PostgreSQL's own extension catalog directly.

Two more read-back helpers round out the set: one for a scalar text value, and one for a value that's a whole structure (an object or array) rather than a scalar. On-event checks use the structure-reading one to get the calling event's record_pk/detail back out of a check routine — see pghf._event_check_result() there for the ready-made example.

Continue to Adding a Threshold.