pgbus 0.21.2 → 0.21.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2dece606e269b4f406a3ba3d786facbdd53aedd675fda239803c5136e241678
-  data.tar.gz: 8498b9396aa4577f18b5e2e7793e82e9a67ce896b7495f061d51bd28e56112a1
+  metadata.gz: 34cf3117ba1bd7fdc9355f8593496af02af9e7e878efc5247856ba2afd7533e8
+  data.tar.gz: b301f2fcf44e83d9438ece6df8f7e94bb627ea91b83070e8e56ce6e3a10f66ae
 SHA512:
-  metadata.gz: 7032434023b3253d81e3c6668a4db3481a500a1421cce80fe94a45f235a244be23da1b0e25ec3657acbaaee4ba11c17e56891d4c401010f22340ae5635f0f55a
-  data.tar.gz: 76e5a0d5dd1343274848660e7ba2b6389b14c955551117b1b9a0821a994960ece32a46e6bedfccd4f2e9ddae3326aa37e3f11cfd3bea70edf78a76c3c6e3961f
+  metadata.gz: 95ccb84dcc956d3d4e483976ee7e62f8fb4525622761e9f767c3cf9237b9de7069c36ab5aba05820a0acbe3da564ca105add4512b010e085dcb11a51ffb97fd8
+  data.tar.gz: cf6fe7554b273ad00988f449a18410ba456520f808337a316671302fcef507e16037e8a64764bb08130521337be065fdc6b9939a7ea788afa872db0423f9775a

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [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.
@@ -17,6 +43,10 @@
 - **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/README.md

@@ -1260,7 +1260,7 @@ All tools below are read-only — none mutates state, and there is no raw-SQL pa
 
 | Tool | Purpose |
 |------|---------|
-| `pgbus_health` | One-call verdict: `OK` / `DEGRADED` / `STALLED`. STALLED is the silent-worker-wedge signal (visible backlog while workers heart-beat but don't claim). Suitable for automated alerting. |
+| `pgbus_health` | One-call verdict: `OK` / `DEGRADED` / `STALLED`. STALLED is the silent-worker-wedge signal: a worker reports its claim loop stalled, or a visible backlog older than `health_unclaimed_grace` (default 60s) while workers heart-beat but don't claim. The summary carries `oldest_unread_claimable_age_sec`. Suitable for automated alerting. |
 | `pgbus_queues` | All queues: depth, visible count, oldest-message age, paused state. |
 | `pgbus_queue_detail` | Per-queue metrics + paused state + table health (dead tuples, bloat, vacuum age). |
 | `pgbus_processes` | Every process with kind, pid, heartbeat age, and `healthy`/`stale`/`stalled` status. |
@@ -1348,7 +1348,7 @@ For the **HTTP** transport, point the client at the mounted URL with a streamabl
 
 For orchestrators like Kubernetes, Pgbus exposes two HTTP probes: `/livez` (is the serving process up?) and `/readyz`. Readiness means different things in the two places the probes are served:
 
-- **Mounted in Rails** (`Pgbus::Web::HealthApp`): `/readyz` runs the cluster-wide `OK` / `DEGRADED` / `STALLED` verdict, same as the MCP `pgbus_health` tool — `STALLED` (visible backlog while workers heart-beat but don't claim) fails readiness.
+- **Mounted in Rails** (`Pgbus::Web::HealthApp`): `/readyz` runs the cluster-wide `OK` / `DEGRADED` / `STALLED` verdict, same as the MCP `pgbus_health` tool — `STALLED` (a never-claimed backlog older than `health_unclaimed_grace` while workers heart-beat but don't claim) fails readiness.
 - **Standalone from the supervisor** (`health_port`): `/readyz` is **container-local** — did *this* supervisor finish booting, and are all the children *it* forked alive? That is the signal a rolling deploy's health gate needs; the cluster verdict would let a brand-new container pass on the strength of the *old* container's workers.
 
 | Path | Method | 200 | 503 | Touches DB |
@@ -2560,6 +2560,7 @@ Curated headline options for the README. The full operator reference (with types
 | `statsd_port` | `8125` | StatsD UDP port (used when `metrics_backend = :statsd`) |
 | `health_port` | `nil` | Port for standalone HTTP liveness/readiness probes served by the supervisor; nil disables |
 | `health_bind` | `"127.0.0.1"` | Bind address for the standalone health server |
+| `health_unclaimed_grace` | `60` | Seconds a visible, never-read message must have been claimable before the health verdict reports it as never claimed (`STALLED`); `0` counts any such message |
 | `pgmq_schema_mode` | `:auto` | PGMQ schema install mode (`:auto`, `:extension`, `:embedded`) |
 | `doctor_on_boot` | `nil` | Run doctor inside the booting supervisor: `nil`/`false` = off, `:report` = log and boot, `:strict` = refuse to boot on a fatal check. Also via `--doctor` / `--doctor-strict`. |
 | `eager_validation` | `true` | Run `Configuration#validate!` automatically after the `Pgbus.configure` block yields; an invalid value raises `Pgbus::ConfigurationError` at boot. Set `false` to suppress and validate manually. |

data/lib/pgbus/configuration.rb

@@ -241,6 +241,14 @@ module Pgbus
     # plain TCPServer bound to `health_bind` (default localhost).
     attr_accessor :health_port, :health_bind
 
+    # Seconds 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" (issue #589). Below it a worker's next
+    # poll is still coming, so a fresh enqueue or a delayed job whose wait just
+    # expired no longer reads STALLED. 0 restores the pre-0.22 rule (any
+    # visible read_ct = 0 row counts). Default 60.
+    attr_reader :health_unclaimed_grace
+
     # Streams (turbo-rails replacement, SSE-based)
     attr_accessor :streams_enabled, :streams_path, :streams_signed_name_secret,
                   :streams_default_retention, :streams_retention, :streams_heartbeat_interval, :streams_peer_close_interval,
@@ -419,6 +427,7 @@ module Pgbus
       # HTTP health endpoints — nil port disables the standalone server.
       @health_port = nil
       @health_bind = "127.0.0.1"
+      @health_unclaimed_grace = 60
 
       @streams_enabled = true
       @streams_path = nil
@@ -951,6 +960,8 @@ module Pgbus
 
       raise Pgbus::ConfigurationError, "health_bind must be a non-empty String" unless health_bind.is_a?(String) && !health_bind.empty?
 
+      validate_health_unclaimed_grace!
+
       raise Pgbus::ConfigurationError, "statsd_host must be a non-empty String" unless statsd_host.is_a?(String) && !statsd_host.empty?
 
       unless statsd_port.is_a?(Integer) && statsd_port.between?(1, 65_535)
@@ -1539,6 +1550,14 @@ module Pgbus
       @recurring_execution_retention = coerce_duration!(value, :recurring_execution_retention)
     end
 
+    # Not coerce_duration!: 0 is valid here (the pre-0.22 rule), and nil is not
+    # a "disabled" sentinel. A Duration becomes integer seconds; anything else
+    # is kept for validate! to judge.
+    def health_unclaimed_grace=(value)
+      duration = defined?(ActiveSupport::Duration) && value.is_a?(ActiveSupport::Duration)
+      @health_unclaimed_grace = duration ? value.to_i : value
+    end
+
     # recurring_tasks_file (singular) is deprecated in favor of the plural
     # recurring_tasks_files. The engine still writes the singular internally to
     # record which default file was loaded, so it stays a plain accessor; the
@@ -1867,6 +1886,14 @@ module Pgbus
       raise Pgbus::ConfigurationError, "immediate_shutdown_grace must be a finite number >= 0"
     end
 
+    # A finite real number >= 0; nil is not "off" (0 is).
+    def validate_health_unclaimed_grace!
+      grace = health_unclaimed_grace
+      return if grace.is_a?(Numeric) && grace.real? && grace.finite? && grace >= 0
+
+      raise Pgbus::ConfigurationError, "health_unclaimed_grace must be a finite number of seconds >= 0, got #{grace.inspect}"
+    end
+
     def validate_positive_duration!(numeric, name)
       raise Pgbus::ConfigurationError, "#{name} must be a positive number, got #{numeric}" unless numeric.positive?
 

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/mcp/health_analyzer.rb

@@ -35,8 +35,12 @@ module Pgbus
       # a multi-KB log line (issue #367 minor).
       NAME_LIMIT = 10
 
-      def initialize(data_source)
+      # +grace+ overrides Pgbus.configuration.health_unclaimed_grace (issue #589):
+      # seconds a visible read_ct=0 message must have been claimable before it
+      # counts as "never claimed". nil reads the config when the verdict runs.
+      def initialize(data_source, grace: nil)
         @data_source = data_source
+        @grace = grace
       end
 
       # Returns a machine-readable verdict hash suitable for both interactive
@@ -81,7 +85,9 @@ module Pgbus
           status: status,
           reasons: stalled + degraded,
           checked_at: Time.now.utc.iso8601,
-          summary: build_summary(queues, non_dlq, processes, health)
+          summary: build_summary(queues, non_dlq, processes, health).merge(
+            oldest_unread_claimable_age_sec: oldest_unread_age(drained)
+          )
         }
       end
 
@@ -139,7 +145,8 @@ module Pgbus
                      "while #{active_backlog.size} queue(s) have visible backlog: #{backlog_names(active_backlog)}"
         elsif live_drainers.any? && drained_backlog.any? && any_unread?(drained_backlog)
           unread = drained_backlog.select { |q| unread?(q) }
-          reasons << "#{unread.size} queue(s) have visible messages with read_ct=0 (never claimed) " \
+          reasons << "#{unread.size} queue(s) have visible messages with read_ct=0 " \
+                     "(never claimed#{unread_age_clause(unread)}) " \
                      "while #{live_drainers.size} draining process(es) are alive: #{backlog_names(unread)}"
         end
         reasons
@@ -211,10 +218,39 @@ module Pgbus
       #
       # When metrics don't expose the count (an old hash / a stubbed test) we
       # conservatively treat the queue as unread so we never miss the wedge.
+      #
+      # Issue #589: the oldest such row must also have been claimable for at
+      # least the grace. A fresh enqueue, or a delayed job whose wait just
+      # expired, is visible with read_ct=0 until a worker's next poll, so
+      # without the grace a healthy fleet read STALLED (and /readyz 503) on a
+      # large share of checks. An unknown age (key missing or nil) stays
+      # conservative and counts.
       def unread?(queue)
         return true unless queue.key?(:visible_unread_length)
+        return false unless queue[:visible_unread_length].to_i.positive?
+
+        age = unread_age(queue)
+        age.nil? || age >= grace
+      end
+
+      def grace
+        @grace || Pgbus.configuration.health_unclaimed_grace
+      end
+
+      def unread_age(queue)
+        queue[:oldest_unread_claimable_age_sec]
+      end
+
+      # Oldest known unread claimable age over +queues+, nil when none is known.
+      def oldest_unread_age(queues)
+        queues.filter_map { |q| unread_age(q) }.max
+      end
 
-        queue[:visible_unread_length].to_i.positive?
+      # ", oldest claimable for 74s" so an operator can tell a wedge from a
+      # spike; empty when no flagged queue reports an age.
+      def unread_age_clause(queues)
+        age = oldest_unread_age(queues)
+        age ? ", oldest claimable for #{age}s" : ""
       end
 
       # Join backlog queue names for a reason string, truncated so a flagged

data/lib/pgbus/mcp/tools/health_tool.rb

@@ -13,8 +13,10 @@ module Pgbus
         description <<~DESC
           Top-level pgbus health verdict. Returns OK, DEGRADED, or STALLED with
           the specific reasons. STALLED means the silent-wedge condition:
-          queues have visible backlog while workers are heart-beating but not
-          claiming (or a worker's claim loop has stalled). DEGRADED covers
+          queues hold a visible, never-claimed backlog older than
+          health_unclaimed_grace (default 60s) while workers are heart-beating
+          but not claiming (or a worker's claim loop has stalled); the summary's
+          oldest_unread_claimable_age_sec tells a wedge from a spike. DEGRADED covers
           stale processes, paused queues holding a backlog, dead-letter
           buildup, or a long-running transaction pinning the MVCC horizon. Use
           this first when triaging — it summarizes the whole system in one call

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;
+$$;