Collection Engine

pghf.execute_check_run(p_run_key text DEFAULT NULL, p_check_run_id uuid DEFAULT NULL, INOUT p_run_id uuid DEFAULT NULL, p_target_version int DEFAULT NULL, p_amcheck_tables text[] DEFAULT NULL, p_pg_visibility_tables text[] DEFAULT NULL, p_critical_only boolean DEFAULT false)

The generic dispatch engine. Runs every member of a named suite, in order, committing after each one. It has zero built-in knowledge of any particular check or suite — it's driven entirely by suite membership and each check's registered backing function. Deliberately not SECURITY DEFINER (see The Access Model): checks run as whoever actually calls this procedure. Must be invoked as a standalone CALL statement.

Parallel mode: for a suite created with p_use_pg_relay => true, and with the pg_relay extension installed, each qualifying check is enqueued on pg_relay channel pghf_check instead of being run inline — pg_relay's workers then execute them in parallel via pghf.execute_relay_check(). Blackout- and qualification-skips are still logged inline (never enqueued), and any failure to use pg_relay — extension absent, channel unregistered or inactive — falls back to sequential execution with a notice or warning rather than failing the run; the run record's run_via_pg_relay flag records what actually happened. In this mode, this procedure returning means submission finished, not the run: the finish time is stamped by whichever worker lands the final result. See Parallel Dispatch (pg_relay) and the User Guide chapter.

Parameter	Type	Mandatory	Default	Description
p_run_key	text	One of p_run_key/p_check_run_id required	empty	Suite to run, by name.
p_check_run_id	uuid	One of p_run_key/p_check_run_id required	empty	Suite to run, by internal identifier.
p_run_id	uuid (input/output)	No	empty = a new one is generated	Pass an existing value to reuse a specific run ID; otherwise a fresh one is generated and handed back to you.
p_target_version	int	No	empty	Recorded as run configuration; read by the pg_upgrade-readiness checks.
p_amcheck_tables	text[]	No	empty	Recorded as run configuration, for checks that verify specific tables with the amcheck extension.
p_pg_visibility_tables	text[]	No	empty	Recorded as run configuration, for checks that inspect specific tables with the pg_visibility extension.
p_critical_only	boolean	No	false	When true, a member is excluded (SKIPPED, never invoked) unless pghf.alert_status.current_status for that check is exactly 'critical' right now — a never-evaluated check counts as not critical. Exact match only (a check ranked even higher, e.g. 'error_in_performing_check', is not included). In parallel mode this is checked once at submission and again at worker-dispatch time (carried in the pg_relay payload — see Parallel Dispatch), covering the gap between enqueue and a worker picking it up. A pure recommendation-composition tool — this project schedules nothing itself; see Scheduling Health Checks for the full design discussion and intended usage pattern.

Returns: the run ID, via the input/output parameter. This is a procedure. Inserts one run record and one raw-result record per suite member, and stamps a finish time on completion (in parallel mode, completion happens when the last worker's result lands — see above).

pghf.execute_check(p_check_id text, INOUT p_run_id uuid DEFAULT NULL, p_severity text DEFAULT NULL, p_record_pk jsonb DEFAULT NULL, p_detail jsonb DEFAULT NULL, p_target_version int DEFAULT NULL, p_amcheck_tables text[] DEFAULT NULL, p_pg_visibility_tables text[] DEFAULT NULL)

Runs and logs ONE check by ID, standalone — not a suite member, not on any polling cadence. The top-level-only half of the on-event pair (see On-Event Checks for the full model): a thin wrapper around pghf.execute_check_event() (below) that adds one COMMIT after it. For a human or orchestrator running one check on demand — ad hoc testing, a one-off manual run — without building a whole suite for it. Must be invoked as a bare top-level CALL, same rule as pghf.execute_check_run() — never from inside a trigger or function; use pghf.execute_check_event() there instead. Works on a check of either execution_mode — a 'polled' check run this way behaves exactly as it would as a manual, unscheduled invocation. Deliberately not SECURITY DEFINER, same reasoning as pghf.execute_check_run().

Parameter	Type	Mandatory	Default	Description
p_check_id	text	Yes	—	The check to run, by ID.
p_run_id	uuid (input/output)	No	empty = a new one is generated	Same convention as pghf.execute_check_run().
p_severity	text	No	empty	The calling event's own verdict — one of ok/info/warning/critical, validated immediately (raises on anything else, before the run is even created). Not a measurement: see On-Event Checks.
p_record_pk	jsonb	No	empty	The offending row's primary key, as a keyed object — {"id": 123}, or {"tenant_id": 1, "job_id": 2} for a composite key. Raises if supplied but not a jsonb object.
p_detail	jsonb	No	empty	Any other context worth keeping — free-form.
p_target_version / p_amcheck_tables / p_pg_visibility_tables	—	No	empty	Recorded as run configuration, same as the identically-named parameters on pghf.execute_check_run().

Returns: the run ID, via the input/output parameter. p_severity/p_record_pk/p_detail all default to empty and are entirely optional — a routine that measures and collects its own data instead, judged by a real threshold, ignores them and works exactly as any other check would.

pghf.execute_check_event(p_check_id text, INOUT p_run_id uuid DEFAULT NULL, p_severity text DEFAULT NULL, p_record_pk jsonb DEFAULT NULL, p_detail jsonb DEFAULT NULL, p_target_version int DEFAULT NULL, p_amcheck_tables text[] DEFAULT NULL, p_pg_visibility_tables text[] DEFAULT NULL)

Runs and logs ONE check by ID, standalone — the trigger-safe half of the on-event pair. Identical parameters and behavior to pghf.execute_check() above, except this one never commits, which is what makes it safe to CALL from inside a trigger or any other atomic execution context — PostgreSQL disallows a procedure that itself commits from being called from one. Every real on-event trigger calls this, not pghf.execute_check().

Auto-resolves the reserved check_runs row (run_key = 'event_alerts', seeded by pghf.seed_data()) that every on-event run is grouped under — raises if it's missing (i.e. pghf.seed_data() was never run on this database). Applies the same qualification gate (min_pg_version/max_pg_version/requires_topology) and 'run'-mode blackout gate pghf.execute_check_run() applies per suite member, then the same invoke / "value"-key contract-check / error-capture / pghf._log_result() sequence, for the one named check. Pins search_path = pg_catalog, public, so a check's behavior doesn't depend on the calling trigger's own search path.

p_severity/p_record_pk/p_detail are staged into run configuration for the check's own routine to read back — pghf._event_check_result() does this for the common case, packaging them straight into observed, so a check using this pattern can be a one-line wrapper around it. Pair with pghf.evaluate_passthrough_severity() as the check's evaluator_routine to get the supplied severity into a real evaluation.

One gotcha to know before your first trigger: p_run_id is INOUT — omitting it works fine from a bare top-level client CALL (the default NULL applies), but PostgreSQL requires a writable target for an INOUT parameter whenever CALL is issued from inside PL/pgSQL, trigger bodies included. Omitting it there raises procedure parameter "p_run_id" is an output parameter but corresponding argument is not writable. The fix: declare v_run_id uuid; in the trigger and pass it explicitly, even unused — see the worked trigger example in On-Event Checks.

Returns: the run ID, via the input/output parameter. Never commits — the caller's own transaction (the trigger's triggering statement, typically) does that.

Continue to Parallel Dispatch (pg_relay).