Skip to content

Actions → on_state Notifications

Earlier versions of this framework had a separate actions subsystem: user-authored functions that fired on every evaluation whose confirmed severity matched, throttled by a cooldown — as distinct from events, which fired only on transitions. Those two ideas are now one Notifications subsystem, and everything actions did is a notification with trigger_mode => 'on_state'.

If you're looking for what actions used to do — "run my function every time this check is at severity X, throttled" — here it is:

-- "act on the state" : one function per severity result, per occurrence, throttled
SELECT pghf.create_notification('capture blockers', 'function', p_check_id => 'PGHF04-002',
    p_trigger_mode    => 'on_state',
    p_severities      => ARRAY['warning','critical'],
    p_routine         => 'my_schema.capture_lock_state(bigint, bigint, jsonb)'::regprocedure,
    p_function_args   => '{"keep_days": 7}'::jsonb,
    p_cooldown_minutes => 30, p_run_sequence => 10);

-- a recovery hook: a different routine, on ok
SELECT pghf.create_notification('recovered', 'function', p_check_id => 'PGHF04-002',
    p_trigger_mode => 'on_state', p_severities => ARRAY['ok'],
    p_routine => 'my_schema.close_ticket(bigint, bigint, jsonb)'::regprocedure);

What carried over, unchanged in spirit:

  • A different routine per severity result — register one on_state notification per severity (ARRAY['critical'], ARRAY['ok'], …). This is exactly the per-severity on_* toggles, made explicit.
  • Per-occurrence firing — on_state fires on every matching evaluation. For an on-event check, that means one notification per distinct occurrence (500 → 500). With p_cooldown_minutes => 0 (the default) nothing is throttled; set a cooldown to suppress a recurring problem.
  • Engine-guaranteed cooldown + anti-flap — p_cooldown_minutes, measured from the last firing; an intervening ok never resets it.
  • run_sequence ordering, exception isolation, and a durable log — firings journal to the shared outbox pghf.notification_log; the routine reports its own outcome with pghf.mark_notification_delivered(). A routine that raises is caught, logged 'failed', and the next one still runs.

What's new relative to actions: a notification can also be category- or global-scoped (actions were check-only), and its firing lands in the same durable outbox every other notification uses — so the pg_relay_notifier and "your own delivery" paths are identical whether you fire on change or on state.

The full model, the delivery kinds, wiring your own consumer, and the optional pg_relay_notifier path are in the Notifications book. For the concept in one page, see Notifications at a Glance.

Continue to psql Shortcuts.