pgbus 0.21.3 → 0.21.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afa142ad44c901764a77528d7e387f708321353b5323c6dafcf23577cd27556e
-  data.tar.gz: 3bdcb708e9547c70115ccc9babd430d038a8b0ffb483faf615842a5a96cbbdff
+  metadata.gz: 34cf3117ba1bd7fdc9355f8593496af02af9e7e878efc5247856ba2afd7533e8
+  data.tar.gz: b301f2fcf44e83d9438ece6df8f7e94bb627ea91b83070e8e56ce6e3a10f66ae
 SHA512:
-  metadata.gz: 3204bb1c094c7765ca32942b76857774e6696070b3b1787057b06da5f185d55de3069397bb1deb1dbf7221daf22eb064dddcb7a7906471e40fddafd5cf14cb38
-  data.tar.gz: 28c7d2ff21d9c8f97a2db27694c1e21184c9549d5af9cbebbef7244e3690d14b13aa546f79d006eb14104189ca3246d1416a6bb1679d59cfe80353d59511e6e5
+  metadata.gz: 95ccb84dcc956d3d4e483976ee7e62f8fb4525622761e9f767c3cf9237b9de7069c36ab5aba05820a0acbe3da564ca105add4512b010e085dcb11a51ffb97fd8
+  data.tar.gz: cf6fe7554b273ad00988f449a18410ba456520f808337a316671302fcef507e16037e8a64764bb08130521337be065fdc6b9939a7ea788afa872db0423f9775a

data/CHANGELOG.md

@@ -1,11 +1,36 @@
 ## [Unreleased]
 
+## [0.21.4] - 2026-10-28
+
+### Added
+
+- **`Pgbus::Event#dig` reads a nested payload value, the nested counterpart of `Event#[]` (issue #594).** `event.dig("meta", "type")` reads Symbol keys as Strings at every level (payloads are JSON-decoded) and passes Integer indexes through (`event.dig("data", "items", 0, "id")`); a missing key or a payload that is not a Hash returns `nil`, as `#[]` does, and an intermediate value without `#dig` raises `TypeError`, as `Hash#dig` does. Refs #594.
+
+### Changed
+
+- **PGMQ: vendored schema v1.13.1, a security release upstream asks everyone on 1.13.0 or earlier to take (issue #586).** Every PGMQ function pins `search_path = pg_catalog, pg_temp` and schema-qualifies its built-ins, so a role that can create objects on another role's search path can no longer shadow a built-in and run code with that role's privileges. `pg_monitor` loses `SELECT` on every table and sequence in the `pgmq` schema: it keeps `SELECT` on `pgmq.meta`, `SELECT (vt, enqueued_at)` on each queue table and `SELECT` on each queue's msg_id sequence, what `pgmq.metrics()`, `pgmq.metrics_all()` and `pgmq.list_queues()` need; a monitoring role that read message payloads through `pg_monitor` no longer can. Fresh embedded installs get 1.13.1. Existing *embedded* installs: `rake pgbus:pgmq:status`, then `rails generate pgbus:upgrade_pgmq` + `rails db:migrate` (`rails db:migrate:pgbus` on a separate-database install). Its new fixup (`lib/pgbus/pgmq_schema/fixups/pgmq_v1.13.1.sql`, upstream's migration blocks) revokes `pg_monitor`'s default privileges and whole-table grants in `pgmq`, grants the metrics columns and sequence on every existing queue, and rebinds a PGMQ column default that resolved to `now()` or `to_timestamp()` outside `pg_catalog`; a grant the migrating role cannot revoke raises a `WARNING` starting `pgmq:` instead of failing (Rails logs it only with `config.active_record.db_warnings_action` set; otherwise it goes to stderr), and a default it cannot alter stops the migration. Upstream's default rebinding selects extension member tables only, which would skip every embedded install, so the fixup selects pgmq's tables by name. `Pgbus::PgmqSchema.install_sql` now restores the caller's `search_path` after the vendored SQL, because 1.13.1 pins it with a transaction-local setting that would otherwise outlive the install inside a migration and send the next unqualified `CREATE TABLE` to `pg_catalog`. An `:extension` install gets 1.13.1 from `ALTER EXTENSION pgmq UPDATE`. Refs #586.
+
+### Fixed
+
+- **NOTIFY wakeups fire for a queue whose name has an uppercase letter (issue #586).** PGMQ's insert trigger rebuilt the queue name from its lowercased table name, which matched no `pgmq.notify_insert_throttle` row, so it never sent the NOTIFY and that queue's workers polled. PGMQ 1.13.1 passes the queue name to the trigger, and the upgrade migration's NOTIFY repair re-creates every queue's trigger that way; the channel, `pgmq.q_<queue name>.INSERT`, keeps the queue name's case, which is what pgbus LISTENs on. Refs #586.
+
+## [0.21.3] - 2026-10-22
+
+### Added
+
+- **`config.health_unclaimed_grace` (default 60 seconds) and the per-queue metric `oldest_unread_claimable_age_sec` (issue #589).** The grace is how long a visible, never-read (`read_ct = 0`) message must have been claimable before the health verdict counts it as "never claimed while draining processes are alive". It takes a number of seconds or an `ActiveSupport::Duration`; `0` restores the old rule (any such message counts), and `validate!` raises `ConfigurationError` on nil, a negative or a non-finite value. `Web::DataSource#queues_with_metrics` and `#queue_detail` report `oldest_unread_claimable_age_sec`, the seconds since the oldest visible `read_ct = 0` message became claimable (`min(vt)`, so a delayed job's age starts when its wait expires and a retried message is left out), nil when there is none. The verdict's `summary` carries it as the oldest over the drained queues, and the STALLED reason names it (`never claimed, oldest claimable for 74s`). `Pgbus::MCP::HealthAnalyzer.new` takes an optional `grace:`. Refs #589.
+
+### Fixed
+
+- **`/readyz` and `pgbus_health` no longer flap to `STALLED` on a healthy fleet (issue #589).** The verdict reported `STALLED` (and the mounted `/readyz` 503) whenever a drained queue held one visible, never-read message while a worker or consumer was alive, however briefly it had been claimable: every enqueue and every delayed job whose wait just expired is such a message until a worker's next poll, so a busy install answered 503 on a large share of checks. That branch now counts a queue only once its oldest such message has been claimable for `health_unclaimed_grace` seconds; a wedged worker still reads `STALLED` after the grace. A queue hash without the age (an older or stubbed data source) still counts at once. The worker-reported stalled branch (heart-beating, claim loop not advancing) is unchanged. Refs #589.
+
+## [0.21.2] - 2026-10-21
+
 ### Added
 
 - **`config.boot_timeout` (default 120 seconds): the supervisor kills a child that never checks in (issue #587).** A fork checks in when it registers its `pgbus_processes` row on this host or writes its first liveness byte. One that has done neither `boot_timeout` seconds after the fork is logged at ERROR, sent `TTIN`, given 2 seconds, then SIGKILLed, and the normal restart path forks it again. A boot-deadline kill always counts as a crash, whatever the child's uptime, so a boot that hangs every time is re-forked with the crash-loop backoff (1 s doubling to 60 s) instead of every `boot_timeout`. Applies to workers, consumers, the dispatcher, the scheduler and the outbox poller. `nil` turns it off; anything else must be a positive number, or `validate!` raises `ConfigurationError`. When the watchdog's read of the process table fails, the boot deadline waits for a pass that can read it. Refs #587.
 - **A process whose registration in `pgbus_processes` failed at start retries it on each heartbeat (issue #587).** It used to stay without a row for good after one failed `create!` (a database blip at boot); a dispatcher, scheduler or outbox poller in that state would now be killed by the boot deadline even though it runs. Refs #587.
 - **`kill -TTIN <child pid>` logs every thread of a pgbus child with its backtrace at ERROR; the child keeps running (issue #587).** The watchdog sends it before every SIGKILL (boot timeout or stalled loop), so a hang is diagnosable from the log. Best effort: a child blocked in native code holding the GVL does not answer. Refs #587.
-- **`config.health_unclaimed_grace` (default 60 seconds) and the per-queue metric `oldest_unread_claimable_age_sec` (issue #589).** The grace is how long a visible, never-read (`read_ct = 0`) message must have been claimable before the health verdict counts it as "never claimed while draining processes are alive". It takes a number of seconds or an `ActiveSupport::Duration`; `0` restores the old rule (any such message counts), and `validate!` raises `ConfigurationError` on nil, a negative or a non-finite value. `Web::DataSource#queues_with_metrics` and `#queue_detail` report `oldest_unread_claimable_age_sec`, the seconds since the oldest visible `read_ct = 0` message became claimable (`min(vt)`, so a delayed job's age starts when its wait expires and a retried message is left out), nil when there is none. The verdict's `summary` carries it as the oldest over the drained queues, and the STALLED reason names it (`never claimed, oldest claimable for 74s`). `Pgbus::MCP::HealthAnalyzer.new` takes an optional `grace:`. Refs #589.
 - **The supervisor's standalone `/readyz` body carries `forked` (issue #587).** `forked` is the fork-table size (what `live` used to be); `live` now counts the children that have checked in. `Pgbus::Process::ReadinessSnapshot` gains `forked:`, defaulting to `live`. Refs #587.
 
 ### Changed
@@ -14,11 +39,14 @@
 
 ### Fixed
 
-- **`/readyz` and `pgbus_health` no longer flap to `STALLED` on a healthy fleet (issue #589).** The verdict reported `STALLED` (and the mounted `/readyz` 503) whenever a drained queue held one visible, never-read message while a worker or consumer was alive, however briefly it had been claimable: every enqueue and every delayed job whose wait just expired is such a message until a worker's next poll, so a busy install answered 503 on a large share of checks. That branch now counts a queue only once its oldest such message has been claimable for `health_unclaimed_grace` seconds; a wedged worker still reads `STALLED` after the grace. A queue hash without the age (an older or stubbed data source) still counts at once. The worker-reported stalled branch (heart-beating, claim loop not advancing) is unchanged. Refs #589.
 - **A child that hangs before its first liveness signal is killed and forked again, and `/readyz` no longer counts it as live (issue #587).** A fork stuck between `fork` and its first check-in (in an initializer, the eager load or a connection) never exited, so nothing reaped it, and the watchdog skipped it because no liveness channel had spoken; the container-local `/readyz` counted it as live because it was in the fork table, so a rolling deploy passed its health gate with a dead capsule. The boot deadline above now kills it, and `/readyz` stays at 503 `DEGRADED` (`live < expected`) until every child has checked in. A dispatcher, scheduler or outbox poller checks in through its process row, which the watchdog reads every 10 seconds, so `/readyz` turns 200 up to 10 seconds after the last one registers, and stays at 503 while the database is unreachable at boot (those children cannot be seen to be alive). The watchdog reads only this host's process rows last beaten since the fork, so a row another container wrote under the same pid, or one a SIGKILLed predecessor left behind (a container restarted in place reuses its hostname and pids), no longer vouches for a local child or hides a stalled loop. Refs #587.
 - **A failed job's retry backoff applies under priority routing (issue #582).** With `priority_levels > 1` the executor set the backoff's visibility timeout on the logical queue's base table, which priority routing never creates; the call raised, was logged at debug, and the job came back after the read's visibility timeout instead of its backoff delay. The backoff now goes to the `_pN` sub-queue the worker read the message from, as the visibility heartbeat and the archive already did. Refs #582.
 - **Two priority sub-queues' failures with the same msg_id keep a row each (issue #583).** Each `_pN` sub-queue numbers its messages from its own sequence, and `pgbus_failed_events` was unique on the logical queue and the msg_id, so a second job failing with the same msg_id in another sub-queue overwrote the first one's error and kept its payload: the dashboard showed one failed job where two had failed, Retry and Discard acted on the first job's message and deleted the only row, and the first job's success cleared the second one's failure. Rows now record the physical table (`source_queue`) and are unique on `(queue_name, msg_id, source_queue)`. The executor, the event consumer and the worker's zombie check read, write and clear only the row of the table the message came from. On the Jobs page a failed row joins only its own table's message and shows as an orphan once that message is gone, Retry, Discard and Discard all look the message up in the table the row names, and Discard releases the job's uniqueness lock bounded by when that table's message was sent, not by a sibling sub-queue's. A row written before the migration has no `source_queue` and is treated as before: it can belong to any table of its queue. Refs #583.
 
+## [0.21.1] - 2026-10-19
+
+### Fixed
+
 - **The dashboard's Retry, Discard and Discard all reach a failed job's message under priority routing (issue #577).** A failed-job row records the logical queue only, and with `priority_levels > 1` the message sits in a `_pN` sub-queue, never in the base table. Retry reset the visibility timeout on `pgmq.q_pgbus_<queue>`, which priority routing never creates, and answered "Could not retry job."; Discard and Discard all archived from that same table, so they reported the job discarded while its message stayed queued and ran again. Each sub-queue also numbers its messages from its own sequence, so the msg_id alone could name another job's message in a sibling sub-queue. The dashboard now finds the sub-queue whose message has the row's msg_id and carries the job's `job_id` (`Pgbus::Client#locate_message`, which returns that physical table or nil, and `#locate_messages` for many at once, one query per table), resets or archives the message there, and leaves a same-numbered message elsewhere alone. Discard all locates a queue's messages together and archives them in one batch per table. When no sub-queue holds it, Retry enqueues a fresh copy as before. Without priority routing there is one table and nothing changes, except that a message reusing the msg_id under another `job_id` is no longer reset or archived in the job's place. Refs #577.
 
 ## [0.21.0] - 2026-10-19

data/lib/pgbus/event.rb

@@ -23,6 +23,16 @@ module Pgbus
       payload.is_a?(Hash) ? payload[key.to_s] : nil
     end
 
+    # Nested counterpart of #[]: the first key is read as a String, later
+    # Symbol keys too (payloads are JSON-decoded); Integer indexes are kept.
+    # A non-Hash payload gives nil; an intermediate value without #dig raises
+    # TypeError, as Hash#dig does.
+    def dig(key, *rest)
+      return nil unless payload.is_a?(Hash)
+
+      payload.dig(key.to_s, *rest.map { |k| k.is_a?(Symbol) ? k.to_s : k })
+    end
+
     def to_h
       {
         "event_id" => event_id,

data/lib/pgbus/pgmq_schema/fixups/pgmq_v1.13.1.sql

@@ -0,0 +1,265 @@
+-- PGMQ 1.13.1 table fixup.
+--
+-- Adapted from the upstream migration
+-- pgmq-extension/sql/pgmq--1.13.0--1.13.1.sql at tag v1.13.1
+-- (blob 16cbbe2763ec6508570a80e7ef08b7bee3b11ffd). Only the parts pgbus's
+-- upgrade cannot already reproduce are here: dropping every function and
+-- composite type and re-running the target schema recreates functions and
+-- types, but never touches an existing table, its column defaults or its
+-- grants.
+--
+-- Left out on purpose: upstream's loop that re-creates each queue's NOTIFY
+-- trigger with the queue name as its argument. The upgrade's
+-- reinstall_notify_triggers_sql step replays the new pgmq.enable_notify_insert
+-- for every row of pgmq.notify_insert_throttle, which re-creates the trigger
+-- the same way.
+--
+-- One deliberate deviation from upstream: the rebind-defaults block selects
+-- pgmq's tables by name in the pgmq schema instead of by extension membership
+-- (pg_depend deptype 'e'). An embedded install has no extension, so upstream's
+-- selection would find nothing and the block would never run. The pg_monitor
+-- blocks are upstream's, unchanged.
+--
+-- Every file in this directory MUST be idempotent and self-guarded. The
+-- upgrade migration applies each fixup between the recorded installed version
+-- and the target, and an install whose version was never recorded gets all of
+-- them, so a fixup can be replayed against a database that already has it.
+
+-- Queue tables created by the old functions can retain defaults bound to a
+-- function in a writable schema. Replacing the functions does not replace
+-- those stored expression dependencies. Rebind only PGMQ's own defaults that
+-- refer to a non-catalog now() or to_timestamp(). Include partition children,
+-- since their defaults can be stored separately from the parent.
+DO $pgmq_rebind_defaults$
+DECLARE
+    def RECORD;
+BEGIN
+    FOR def IN
+        WITH RECURSIVE pgmq_tables AS (
+            -- pgbus: pgmq schema tables by name, not extension members (see header).
+            SELECT c.oid, c.relname
+              FROM pg_catalog.pg_class c
+             WHERE c.relnamespace = 'pgmq'::pg_catalog.regnamespace
+               AND c.relkind IN ('r', 'p')
+        ), roots AS (
+            SELECT c.oid AS relid,
+                   CASE c.relname
+                       WHEN 'meta' THEN 'meta'
+                       WHEN 'topic_bindings' THEN 'topic_bindings'
+                       ELSE 'notify_insert_throttle'
+                   END AS kind
+              FROM pgmq_tables c
+             WHERE c.relname IN ('meta', 'topic_bindings', 'notify_insert_throttle')
+            UNION
+            SELECT c.oid, names.kind
+              FROM pgmq_tables core
+              JOIN pgmq.meta m ON core.relname = 'meta'
+              CROSS JOIN LATERAL (
+                  VALUES (pgmq.format_table_name(m.queue_name::pg_catalog.text, 'q'::pg_catalog.text), 'queue'),
+                         (pgmq.format_table_name(m.queue_name::pg_catalog.text, 'a'::pg_catalog.text), 'archive')
+              ) AS names(relname, kind)
+              JOIN pg_catalog.pg_class c
+                ON c.relnamespace = 'pgmq'::pg_catalog.regnamespace
+               AND c.relname = names.relname
+               AND c.relkind IN ('r', 'p')
+        ), managed AS (
+            SELECT relid, kind FROM roots
+            UNION
+            SELECT i.inhrelid, m.kind
+              FROM managed m
+              JOIN pg_catalog.pg_inherits i ON i.inhparent = m.relid
+        )
+        SELECT n.nspname, c.relname, a.attname,
+               pg_catalog.pg_get_expr(ad.adbin, ad.adrelid) AS old_expression,
+               CASE WHEN m.kind = 'notify_insert_throttle'
+                    THEN 'pg_catalog.to_timestamp(0)'
+                    ELSE 'pg_catalog.now()'
+               END AS replacement,
+               EXISTS (
+                   SELECT 1
+                     FROM pg_catalog.pg_depend d
+                     JOIN pg_catalog.pg_proc p ON p.oid = d.refobjid
+                     JOIN pg_catalog.pg_namespace pn ON pn.oid = p.pronamespace
+                    WHERE d.classid = 'pg_catalog.pg_attrdef'::pg_catalog.regclass
+                      AND d.objid = ad.oid
+                      AND d.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
+                      AND pn.nspname <> 'pg_catalog'
+                      AND ((m.kind = 'notify_insert_throttle'
+                            AND p.proname = 'to_timestamp'
+                            AND p.proargtypes[0] = 'pg_catalog.int4'::pg_catalog.regtype
+                            AND pg_catalog.pg_get_expr(ad.adbin, ad.adrelid) =
+                                pg_catalog.format('%I.to_timestamp(0)', pn.nspname))
+                        OR (m.kind <> 'notify_insert_throttle'
+                            AND p.proname = 'now'
+                            AND p.pronargs = 0
+                            AND pg_catalog.pg_get_expr(ad.adbin, ad.adrelid) =
+                                pg_catalog.format('%I.now()', pn.nspname)))
+               ) AS known_shape
+          FROM managed m
+          JOIN pg_catalog.pg_class c ON c.oid = m.relid
+          JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+          JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
+          JOIN pg_catalog.pg_attrdef ad
+            ON ad.adrelid = c.oid AND ad.adnum = a.attnum
+         WHERE ((m.kind = 'meta' AND a.attname = 'created_at')
+             OR (m.kind = 'topic_bindings' AND a.attname = 'bound_at')
+             OR (m.kind = 'notify_insert_throttle' AND a.attname = 'last_notified_at')
+             OR (m.kind = 'queue' AND a.attname = 'enqueued_at')
+             OR (m.kind = 'archive' AND a.attname IN ('enqueued_at', 'archived_at')))
+           AND EXISTS (
+               SELECT 1
+                 FROM pg_catalog.pg_depend d
+                 JOIN pg_catalog.pg_proc p ON p.oid = d.refobjid
+                 JOIN pg_catalog.pg_namespace pn ON pn.oid = p.pronamespace
+                WHERE d.classid = 'pg_catalog.pg_attrdef'::pg_catalog.regclass
+                  AND d.objid = ad.oid
+                  AND d.refclassid = 'pg_catalog.pg_proc'::pg_catalog.regclass
+                  AND pn.nspname <> 'pg_catalog'
+           )
+    LOOP
+        IF NOT def.known_shape THEN
+            RAISE EXCEPTION 'PGMQ upgrade cannot safely rebind custom default on %.%.%: %; inspect the non-catalog function dependency before retrying',
+                def.nspname, def.relname, def.attname, def.old_expression;
+        END IF;
+        BEGIN
+            EXECUTE pg_catalog.format(
+                'ALTER TABLE %I.%I ALTER COLUMN %I SET DEFAULT %s',
+                def.nspname, def.relname, def.attname, def.replacement
+            );
+        EXCEPTION WHEN insufficient_privilege THEN
+            RAISE EXCEPTION 'PGMQ upgrade cannot rebind default on %.%.%; use a role that can update the extension and alter the table, or a superuser',
+                def.nspname, def.relname, def.attname;
+        END;
+    END LOOP;
+END
+$pgmq_rebind_defaults$;
+
+-- pg_monitor could read every table and sequence in the pgmq schema, including
+-- queue and archive tables. Replace that broad access with the minimum needed
+-- by pgmq.metrics(), pgmq.metrics_all(), and pgmq.list_queues().
+
+-- 1. Remove default privileges that granted SELECT on every new table and
+-- sequence. The grantor can differ from the role running this upgrade.
+DO $$
+DECLARE
+    acl RECORD;
+BEGIN
+    FOR acl IN
+        SELECT DISTINCT d.defaclrole::pg_catalog.regrole AS role_name
+          FROM pg_catalog.pg_default_acl d
+          JOIN pg_catalog.pg_namespace n ON n.oid = d.defaclnamespace
+          CROSS JOIN LATERAL pg_catalog.aclexplode(d.defaclacl) a
+         WHERE n.nspname = 'pgmq'
+           AND d.defaclobjtype IN ('r', 'S')
+           AND a.grantee = 'pg_monitor'::pg_catalog.regrole
+    LOOP
+        BEGIN
+            EXECUTE pg_catalog.format(
+                'ALTER DEFAULT PRIVILEGES FOR ROLE %s IN SCHEMA pgmq REVOKE SELECT ON TABLES FROM pg_monitor',
+                acl.role_name
+            );
+            EXECUTE pg_catalog.format(
+                'ALTER DEFAULT PRIVILEGES FOR ROLE %s IN SCHEMA pgmq REVOKE SELECT ON SEQUENCES FROM pg_monitor',
+                acl.role_name
+            );
+        EXCEPTION WHEN insufficient_privilege OR undefined_object THEN
+            RAISE WARNING 'pgmq: could not remove default privileges of role % granting SELECT to pg_monitor in schema pgmq; run "ALTER DEFAULT PRIVILEGES FOR ROLE % IN SCHEMA pgmq REVOKE SELECT ON TABLES FROM pg_monitor" (and the same ON SEQUENCES) as that role or a superuser', acl.role_name, acl.role_name;
+        END;
+    END LOOP;
+END;
+$$;
+
+-- 2. Revoke whole-relation SELECT from pg_monitor on every relation in pgmq
+-- except meta. Step 4 reports grants that the upgrade role cannot remove.
+DO $$
+DECLARE
+    rel RECORD;
+BEGIN
+    FOR rel IN
+        SELECT DISTINCT c.oid::pg_catalog.regclass AS rel_name,
+               c.relkind = 'S' AS is_sequence
+          FROM pg_catalog.pg_class c
+          JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+          CROSS JOIN LATERAL pg_catalog.aclexplode(c.relacl) a
+         WHERE n.nspname = 'pgmq'
+           AND c.relkind IN ('r', 'p', 'v', 'm', 'f', 'S')
+           AND c.relname <> 'meta'
+           AND a.grantee = 'pg_monitor'::pg_catalog.regrole
+           AND a.privilege_type = 'SELECT'
+    LOOP
+        BEGIN
+            EXECUTE pg_catalog.format(
+                'REVOKE SELECT ON %s %s FROM pg_monitor',
+                CASE WHEN rel.is_sequence THEN 'SEQUENCE' ELSE 'TABLE' END,
+                rel.rel_name
+            );
+        EXCEPTION WHEN insufficient_privilege THEN
+            RAISE WARNING 'pgmq: could not revoke SELECT on % from pg_monitor; run "REVOKE SELECT ON % FROM pg_monitor" as its owner or a superuser', rel.rel_name, rel.rel_name;
+        END;
+    END LOOP;
+END;
+$$;
+
+-- 3. Grant the minimal metrics access on each existing queue. A grant on a
+-- partitioned parent is sufficient because metrics query the parent.
+DO $$
+DECLARE
+    q RECORD;
+    qtable TEXT;
+    qseq TEXT;
+BEGIN
+    FOR q IN SELECT queue_name FROM pgmq.meta LOOP
+        qtable := pgmq.format_table_name(
+            q.queue_name::pg_catalog.text,
+            'q'::pg_catalog.text
+        );
+        qseq := qtable || '_msg_id_seq';
+        IF pg_catalog.to_regclass(pg_catalog.format('pgmq.%I', qtable)) IS NOT NULL THEN
+            BEGIN
+                EXECUTE pg_catalog.format(
+                    'GRANT SELECT (vt, enqueued_at) ON pgmq.%I TO pg_monitor',
+                    qtable
+                );
+            EXCEPTION WHEN insufficient_privilege THEN
+                RAISE WARNING 'pgmq: could not grant SELECT (vt, enqueued_at) on pgmq.% to pg_monitor; run it as the table owner or a superuser so queue metrics work for pg_monitor', pg_catalog.quote_ident(qtable);
+            END;
+        END IF;
+        IF pg_catalog.to_regclass(pg_catalog.format('pgmq.%I', qseq)) IS NOT NULL THEN
+            BEGIN
+                EXECUTE pg_catalog.format(
+                    'GRANT SELECT ON SEQUENCE pgmq.%I TO pg_monitor',
+                    qseq
+                );
+            EXCEPTION WHEN insufficient_privilege THEN
+                RAISE WARNING 'pgmq: could not grant SELECT on sequence pgmq.% to pg_monitor; run it as the sequence owner or a superuser so queue metrics work for pg_monitor', pg_catalog.quote_ident(qseq);
+            END;
+        END IF;
+    END LOOP;
+END;
+$$;
+
+-- 4. Report any heap-like relation that still exposes whole-table SELECT to
+-- pg_monitor. Column grants live in pg_attribute and are not reported here.
+DO $$
+DECLARE
+    leftover TEXT;
+BEGIN
+    SELECT pg_catalog.string_agg(
+               c.oid::pg_catalog.regclass::pg_catalog.text,
+               ', ' ORDER BY c.oid::pg_catalog.regclass::pg_catalog.text
+           )
+      INTO leftover
+      FROM pg_catalog.pg_class c
+      JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      CROSS JOIN LATERAL pg_catalog.aclexplode(c.relacl) a
+     WHERE n.nspname = 'pgmq'
+       AND c.relkind IN ('r', 'p', 'v', 'm', 'f')
+       AND c.relname <> 'meta'
+       AND a.grantee = 'pg_monitor'::pg_catalog.regrole
+       AND a.privilege_type = 'SELECT';
+
+    IF leftover IS NOT NULL THEN
+        RAISE WARNING 'pgmq: pg_monitor still has whole-table SELECT on: %. These may expose message payloads; revoke them as the object owner or a superuser.', leftover;
+    END IF;
+END;
+$$;