docs: evidence-backed functional verification of every documented command

[NikolayS]

Goal

Reach 100% confidence that every command in docs/*.md works exactly as documented — backed by captured evidence, not assertions.

A prior single-agent pass reported "all verified," but its log was a summary, not raw transcripts. This issue tracks independent verification runs that each install sql/pgque.sql on a live Postgres + pg_cron, execute every documented snippet, and post the actual command + actual output as a comment here.

Scope (every runnable command)

• docs/tutorial.md — full walkthrough (create_queue/subscribe/send → tick → receive/ack → nack/retry → DLQ → status/get_consumer_info → start() → teardown)
• docs/installation.md — install, pgque.start() schedules + auto-delivers, manual ticker/maint, role-grant matrix, upgrade, uninstall
• docs/examples.md — fan-out, exactly-once, batch send, recurring cron, DLQ replay
• docs/monitoring.md — status/get_*_info columns, stuck-consumer query
• docs/reference.md — every function/overload exists with documented signature/return/grant
• docs/latency-and-tuning.md, docs/concepts.md — runnable bits

Method

• Independent runs across supported majors (PG 14, 16, 18), each its own container + pg_cron.
• For each documented command: paste the verbatim command and the verbatim output; mark PASS or DISCREPANCY (judge semantic correctness — ids/timestamps/latencies will differ).
• Any real discrepancy → a fix PR linked here.

Known not-auto-testable (note, don't fail on)

• pg_tle packaging path (needs pg_tle in the image / source build)
• Python/Go/TypeScript client code snippets

Verification comments to follow from independent runs.

[NikolayS]

Verification run — PostgreSQL 14 + pg_cron 1.6 — independent run A

Environment

• PostgreSQL: 14.23 (Debian 14.23-1.pgdg13+1) on aarch64, Docker postgres:14
• pg_cron: 1.6 (postgresql-14-cron), shared_preload_libraries='pg_cron', cron.database_name='postgres', PgQue installed in the postgres db (same db cron runs against), so pgque.start() jobs run against the PgQue schema.
• PgQue: 0.2.0 (select pgque.version() → 0.2.0), installed via \i /repo/sql/pgque.sql
• psql run with --no-psqlrc and PAGER=cat.

All docs verified against the working tree at /repo (merged main).

---

tutorial.md — PASS

Receive before tick → empty (the surprising-but-correct case):

select * from pgque.receive('orders', 'processor', 100);
 msg_id | batch_id | type | payload | retry_count | ...
--------+----------+------+---------+-------------+----
(0 rows)

force_next_tick + ticker, then receive (canonical jsonb ordering, retry_count null):

select pgque.force_next_tick('orders'); select pgque.ticker();
select msg_id,batch_id,type,payload,retry_count from pgque.receive('orders','processor',100);
 msg_id | batch_id |  type   |             payload              | retry_count
--------+----------+---------+----------------------------------+-------------
      1 |        1 | default | {"total": 99.95, "order_id": 42} |
(1 row)

ack via \gset, then receive empty:

select batch_id from pgque.receive('orders','processor',100) limit 1 \gset
select pgque.ack(:batch_id);
 ack
-----
   1
... receive again → (0 rows)

nack + retry_count progression (max_retries=2):

-- after nack('0s') + maint_retry_events + tick:
 msg_id | batch_id | retry_count
--------+----------+-------------
   2003 |        3 |           1     <- retry_count=1
   2003 |        4 |           2     <- retry_count=2

(msg_id is 2003 not 2 because force_next_tick bumps the event seq by ticker_max_count*2+1000; the tutorial explicitly says numbers differ. batch_id sequence 1,2,3,4 matches exactly.)

Drive to DLQ (third nack, 2>=2 → dead_letter):

select dl_id, dl_reason, ev_id, ev_retry, ev_data from pgque.dlq_inspect('orders');
 dl_id |   dl_reason   | ev_id | ev_retry |             ev_data
-------+---------------+-------+----------+----------------------------------
     1 | still failing |  2003 |        2 | {"total": 10.00, "order_id": 43}
(1 row)

receive returns 0 rows afterward — event left the main queue. dlq_replay(1) returned a new event id; dlq_purge('orders','0 seconds') returned 0.

status() (manual ticking):

  component   |  status  | detail
--------------+----------+----------------------------------------
 postgresql   | info     | PostgreSQL 14.23 ...
 pgque        | info     | 0.2.0
 scheduler    | manual   | ticker_job_id=NULL, maint_job_id=NULL, tick_period_ms=100 (10.00 ticks/sec)
 ticker       | stopped  | not scheduled (tick_period_ms=100)
 maintenance  | stopped  | not scheduled
 pg_timetable | unavailable | ...
 queues       | info     | 1 queues configured
 consumers    | info     | 1 active subscriptions
(8 rows)

Note: 8 rows here vs the doc's 9-row sample. The doc's extra row is pg_cron | unavailable, which only appears when pg_cron is not installed. With pg_cron installed (this run), there is no pg_cron unavailable row. The prose ("with no scheduler, the scheduler row reads manual") is correct. Not a discrepancy — the doc sample was captured on a host without pg_cron.

get_queue_info / get_consumer_info return the documented columns (ticker_lag, ev_new, last_tick_id; lag, last_seen, pending_events). PASS.

---

installation.md / pgque.start() + pg_cron auto-delivery — PASS

pgque.start() registered the four documented jobs:

select pgque.start();
NOTICE:  pgque started: ticker=1 (10.00 ticks/sec), retry_events=2, maint=3, rotate_step2=4

select jobname, schedule, command from cron.job order by jobname;
      jobname       |  schedule  |                       command
--------------------+------------+------------------------------------------------------
 pgque_maint        | 30 seconds | SET statement_timeout = '25s'; SELECT pgque.maint()
 pgque_retry_events | 30 seconds | set statement_timeout = '25s'; select pgque.maint_retry_events()
 pgque_rotate_step2 | 10 seconds | SELECT pgque.maint_rotate_tables_step2()
 pgque_ticker       | 1 second   | CALL pgque.ticker_loop()
(4 rows)

status() after start() flips to scheduled:

 scheduler   | pg_cron   | ticker_job_id=1, maint_job_id=3, tick_period_ms=100 (10.00 t...
 ticker      | scheduled | scheduler=pg_cron, job_id=1, ...
 maintenance | scheduled | scheduler=pg_cron, job_id=3

Auto-delivery proof (no manual tick): sent {"auto": true} (msg_id 10011), waited, then receive (no force_next_tick/ticker call) returned it after the cron ticker ran:

select msg_id,batch_id,payload from pgque.receive('orders','processor',100);
 msg_id | batch_id |    payload
--------+----------+----------------
  10011 |        7 | {"auto": true}
cron.job_run_details shows pgque_ticker (jobid 1) = "succeeded / CALL" repeatedly.

Role grants / denials — PASS:

set role app_writer; select * from pgque.receive(...);  -> ERROR: permission denied for function receive
set role app_writer; select pgque.send('orders',...);   -> 10012   (OK)
set role app_reader; select pgque.send('orders',...);   -> ERROR: permission denied for function send
set role app_reader; select count(*) from pgque.receive(...); -> 0  (OK)
set role app_reader; select pgque.create_queue('q2');   -> ERROR: permission denied for function create_queue
set role pgque_admin; select pgque.uninstall();         -> ERROR: permission denied for function uninstall
set role pgque_reader; select pgque.version();          -> 0.2.0 (OK)

Sibling reader/writer split, admin-only DDL, owner-only uninstall — all as documented.

Referenced files exist: pgque.sql, pgque_uninstall.sql, pgque-tle.sql, pgque-tle-uninstall.sql. set_tick_period_ms validation matches doc (divisors 1,8,10,25,40,50,125,250,1000 accepted; 3 → ERROR: must be an exact divisor of 1000; 2000 → out-of-range error).

---

examples.md — PASS

Fan-out (3 consumers, same event each via own cursor):

-- audit_logger / notification_sender / analytics_pipeline each:
 msg_id |     payload
--------+-----------------
  10013 | {"order_id": 1}

Exactly-once single-transaction CTE (receive+insert+ack): BEGIN; with msgs/inserted/select ack; COMMIT ran with ack=1 and wrote the row into processed_orders. payload::jsonb->>'order_id' extraction confirmed working (returned 1 for {"order_id":1}).

WRONG snapshot example (send+tick+receive in one txn): the freshly-sent event (id 16019) was correctly excluded from the in-transaction receive — confirming the snapshot rule. PASS.

Batch send:

select pgque.send_batch('orders','order.created',array['{"order_id":1}','{"order_id":2}','{"order_id":3}']::jsonb[]);
     send_batch
---------------------
 {18021,18022,18023}    <- aligned bigint[], one id per payload

Recurring cron.schedule producer registered (jobid 5). DLQ dlq_replay_all record return:

select replayed, failed, first_error from pgque.dlq_replay_all('q2');
 replayed | failed | first_error
----------+--------+-------------
        1 |      0 |

Returns the documented (replayed,failed,first_error) record. Text overload (send('orders','not valid json at all')) stored verbatim with no JSON validation. PASS.

---

monitoring.md — PASS

get_queue_info('orders') and get_queue_info() return all documented columns (ticker_lag, ev_per_sec, ev_new, last_tick_id, queue_ticker_paused, queue_ticker_max_count). get_consumer_info('orders','processor') returns lag, last_seen, pending_events, last_tick, current_batch, next_tick. The stuck-consumer-hunt join query ran verbatim:

 queue_name |    consumer_name    | last_seen | last_tick | last_tick_id | ticks_behind | pending_events
------------+---------------------+-----------+-----------+--------------+--------------+----------------
 orders     | analytics_pipeline  | ...       |        11 |           14 |            3 |           6006
 ...

Dead-letter depth queries (group by dl_queue_id) ran clean. PASS.

---

reference.md — PASS

\df confirmed signatures/returns:

• send — 4 overloads: (queue_name text, payload jsonb|text) and (queue_name text, type_name text, payload jsonb|text) → bigint. MATCH.
• send_batch — 4 overloads, jsonb[]/text[], 2-arg and 3-arg → bigint[]. MATCH.
• receive(i_queue text, i_consumer text, i_max_return integer DEFAULT 100) → SETOF pgque.message. MATCH.
• ack(i_batch_id bigint) → integer. MATCH.
• nack(i_batch_id bigint, i_msg pgque.message, i_retry_after interval DEFAULT '00:01:00', i_reason text DEFAULT NULL) → integer. MATCH (default 60 seconds).
• dlq_replay_all(i_queue_name text, OUT replayed bigint, OUT failed bigint, OUT first_error text) → record. MATCH.
• start() → void, version() → text (granted pgque_reader, returned 0.2.0).

Structural claims verified: 3 inheritance child tables per queue (event_1_0/1/2 under event_1); pgque.tick.tick_snapshot is type pg_snapshot. 91 functions in the pgque schema. The argument names exposed by \df use the i_ prefix (e.g. i_queue, i_consumer) rather than the descriptive queue/consumer names in the prose tables — positional calls (used throughout the docs) work; this is a cosmetic naming-style note, not a behavioral discrepancy.

---

latency-and-tuning.md / concepts.md — PASS

set_tick_period_ms accepts every divisor listed in latency-and-tuning.md (1,8,10,25,40,50,125,250,1000) and rejects 3 (non-divisor) and 2000 (out of range) with the documented messages. The scoped cron.schedule('pgque_purge_cron_log', ...) log-purge job registered successfully. concepts.md is conceptual/heritage; its structural claims (snapshot-diff batching via pg_snapshot, 3-table inheritance rotation) are confirmed above. PASS.

---

Verdict

• Total runnable commands executed: ~70 distinct SQL/psql snippets across 7 docs.
• PASS: all areas — tutorial, installation (+ pg_cron start/auto-delivery), examples, monitoring, reference, latency-and-tuning, concepts.
• DISCREPANCIES: none.

Two non-discrepancy notes for the record:

1. pgque.status() returns 8 rows when pg_cron IS installed (no pg_cron | unavailable row) vs the doc's 9-row sample captured on a pg_cron-less host. Prose is accurate; output is environment-dependent and semantically correct.
2. \df shows internal i_-prefixed argument names (i_queue, i_max_return, etc.) where reference.md prose uses descriptive names. Positional calls — what every doc snippet uses — work correctly. Cosmetic only.

Verified independently on PostgreSQL 14.23 + pg_cron 1.6, PgQue 0.2.0.

[NikolayS]

Verification run — PostgreSQL 16 + pg_cron 1.6 — independent run B

Verifier: independent run B. All commands run verbatim (adapted host/port only) against a fresh container, psql --no-psqlrc PAGER=cat. Docs as on current main.

Environment

• Image: postgres:16 (PostgreSQL 16.11 Debian, aarch64). Container pgque-verify-16, host port 55416.
• pg_cron 1.6 installed (postgresql-16-cron), shared_preload_libraries='pg_cron', cron.database_name='postgres', restarted, create extension pg_cron.
• PgQue installed via \i /repo/sql/pgque.sql. select pgque.version() → 0.2.0.
• PgQue schema lives in the same DB (postgres) as the cron DB, so pgque.start() jobs reach it directly. Auto-delivery verified (below).

Tutorial (docs/tutorial.md) — full end-to-end walk

Step 2-4 create_queue→1, subscribe→1, send(jsonb)→1, receive-before-tick → (0 rows) as documented (the "surprise zero rows" path). PASS.

Step 5 force_next_tick→1, ticker→1, then receive:

 msg_id | batch_id |  type   |             payload              | retry_count
--------+----------+---------+----------------------------------+-------------
      1 |        1 | default | {"total": 99.95, "order_id": 42} |

jsonb canonicalized ("total" before "order_id"), retry_count null on first delivery. PASS.

Step 6 \gset batch_id + ack(:batch_id)→1, then receive → (0 rows). PASS.

Step 7 set_queue_config('orders','max_retries','2')→1. send/force/tick/receive → msg_id 2003 retry_count null. nack(0s)+ack do-block, maint_retry_events→1, force/tick, receive:

 msg_id | batch_id |  type   | payload                          | retry_count
--------+----------+---------+----------------------------------+-------------
   2003 |        3 | default | {"total": 10.00, "order_id": 43} |           1

Same msg_id, new batch_id, retry_count=1 = the redelivery. PASS.

Step 8 (DLQ drive) ran the nack/ack/maint/tick block twice. After 2nd iteration receive → (0 rows). dlq_inspect:

 dl_id |   dl_reason   | ev_id | ev_retry |             ev_data
-------+---------------+-------+----------+----------------------------------
     1 | still failing |  2003 |        2 | {"total": 10.00, "order_id": 43}

Exactly matches the documented coalesce(ev_retry,0) >= max_retries arithmetic. PASS.
dlq_replay(1)→new ev_id 10010, DLQ row removed (0 rows after). dlq_purge('orders','0 seconds')→0. PASS.

Step 9 (health) get_queue_info('orders') returns queue_name/ticker_lag/ev_new/last_tick_id; get_consumer_info('orders','processor') returns lag/last_seen/pending_events; status() returns the component/status/detail rollup. PASS. (Note: with pg_cron installed, status() omits the unavailable pg_cron row the doc shows in its no-cron example — correct behavior, 8 rows vs the doc's illustrative 9.)

pg_cron path + auto-delivery (installation.md Option A, tutorial "where to go from here")

pgque.start() registered 4 jobs:

 jobid |  schedule  |              command               | database | active
-------+------------+------------------------------------+----------+--------
     1 | 1 second   | CALL pgque.ticker_loop()           | postgres | t
     2 | 30 seconds | ...select pgque.maint_retry_events | postgres | t
     3 | 30 seconds | ...SELECT pgque.maint()            | postgres | t
     4 | 10 seconds | SELECT pgque.maint_rotate_tables_step2() | postgres | t

status() flipped to scheduler=pg_cron, ticker/maintenance=scheduled with job ids. PASS.

Auto-delivery: sent an event, waited 4 s with NO manual force/ticker, then receive returned a row; cron.job_run_details for jobid 1 shows succeeded / CALL. The cron ticker materializes ticks unattended. PASS.

Roles (installation.md + reference.md grant table)

Granted pgque_reader to t_reader, pgque_writer to t_writer.

• reader send → ERROR: permission denied for function send (DENY) ✓
• writer receive → ERROR: permission denied for function receive (DENY) ✓
• reader create_queue → ERROR: permission denied for function create_queue (DENY, admin-only) ✓
• writer send → allowed (returns ev id) ✓
• reader dlq_inspect → allowed ✓; reader dlq_replay_all → DENY ✓; writer dlq_replay_all → allowed (replay is a produce action, granted to writer) ✓
• reader version() → 0.2.0 (allowed) ✓; reader status() → DENY (admin-only) ✓

PASS — matches the documented sibling reader/writer split and admin-only lifecycle.

reference.md — signatures/overloads/returns

Dumped all 91 pgque.* functions from pg_proc. Every documented signature, overload set, default, and return type matches the catalog, including:

• send/send_batch ×4 overloads each (text/jsonb, 2/3-arg) → bigint / bigint[]
• receive(...) → SETOF pgque.message, ack→integer, nack(...,interval default '00:01:00',text)→integer
• dlq_replay_all(...) OUT (replayed bigint, failed bigint, first_error text) → record (the documented record shape) ✓
• ticker()/ticker(text)/4-arg external ticker(text,bigint,timestamptz,bigint) ✓
• get_queue_info/get_consumer_info (0/1/2-arg) and get_batch_info OUT columns match the reference tables ✓
• force_next_tick/force_tick, set_tick_period_ms, set_queue_config, cooperative-consumer family, triggers, primitives — all present with documented signatures.

dlq_replay_all('orders') on empty queue → (0, 0, null). PASS.

examples.md

• Fan-out: 3 subscribers, one send+tick → all three receive returned the same msg_id (10013) via independent cursors. PASS.
• Exactly-once: the verbatim begin; with msgs/inserted ... select pgque.ack(...); commit; block populated processed_orders and acked atomically. PASS.
• WRONG snapshot demo (send+force+tick+receive in one txn) → (0 rows) exactly as the doc warns. PASS.
• Batch send send_batch(...,array[...]::jsonb[]) → {14017,14018,14019} aligned ids. PASS.
• Recurring cron cron.schedule('daily_report','0 9 * * *', $$select pgque.send(...)$$) → scheduled. PASS.
• DLQ inspect/replay/replay_all/purge all run with documented return shapes. PASS.
• Payload text vs jsonb: both send(...,'{...}') and send(...,'{...}'::jsonb) accepted. PASS.

monitoring.md

get_queue_info() (all), get_consumer_info() (all), the stuck-consumer join (get_consumer_info JOIN get_queue_info USING(queue_name) with last_tick_id - last_tick as ticks_behind), and the dead_letter depth group by dl_queue_id queries all ran verbatim and returned the documented columns. get_batch_info(batch_id) returned queue_name/consumer_name/lag/seq_start/seq_end for a live batch. unsubscribe('orders','analytics_pipeline')→1. PASS.

latency-and-tuning.md

• set_tick_period_ms: every divisor the doc lists — 1,2,4,5,8,10,20,25,40,50,100,125,200,250,500,1000 — accepted and echoed back. PASS.
• Non-divisor 3 → ERROR: tick_period_ms must be an exact divisor of 1000 between 1 and 1000 (got 3). Out-of-range 1001 → same error class. PASS.
• set_queue_config('orders','ticker_max_count','1000') / 'ticker_max_lag','1 second' → 1. PASS.
• pg_cron log-purge cron.schedule('pgque_purge_cron_log', ...) → scheduled. PASS.

concepts.md

Prose/architecture doc; no new runnable SQL beyond what the other docs exercise. The snapshot-rule claim ("insert and the tick must commit in separate transactions") is empirically confirmed by the WRONG-snapshot demo above. PASS (no executable discrepancies).

---

Final verdict

• Docs walked: tutorial, installation, examples, monitoring, reference, latency-and-tuning, concepts (7 of 7).
• Distinct runnable flows executed: ~45+ (tutorial steps 2-9, pg_cron start + auto-delivery, 7 role checks, full reference signature audit of 91 functions, 7 example recipes, 6 monitoring queries, tick-period divisor sweep + 2 rejections, 2 set_queue_config, get_batch_info, cron purge).
• PASS count: all flows PASS.
• Discrepancies: none. (One non-issue: status() shows 8 rows here because pg_cron is installed, vs the tutorial's illustrative 9-row no-cron example — this is correct, documented behavior, not a discrepancy. Numeric msg_id/tick values differ from doc examples exactly as the tutorial says they will, since force_next_tick advances the sequence.)

Independent run B: PgQue 0.2.0 docs work as written on PostgreSQL 16.11 + pg_cron 1.6.

[NikolayS]

Verification run — PostgreSQL 18 + pg_cron 1.6 — independent run C

Environment

• postgres:18 Docker image → PostgreSQL 18.1 (Debian 18.1-1.pgdg13+2), aarch64. Container pgque-verify-18, host port 55418, repo mounted read-only at /repo.
• pg_cron WAS installable for PG18: apt-get install postgresql-18-cron → pg_cron 1.6. Configured shared_preload_libraries='pg_cron', cron.database_name='postgres', restarted, create extension pg_cron. PgQue lives in the same postgres db that pg_cron targets, so pgque.start() jobs reach it. (No manual-ticker fallback needed.)
• PgQue installed via \i /repo/sql/pgque.sql; select pgque.version() → 0.2.0. psql run with --no-psqlrc, PAGER=cat. Tested against current main (/repo).

---

Tutorial (docs/tutorial.md) — PASS

Empty receive before tick (step 4) — 0 rows as documented:

select * from pgque.receive('orders','processor',100);
 msg_id | batch_id | type | payload | retry_count | created_at | extra1..4
(0 rows)

force_next_tick + ticker + receive (step 5):

select pgque.force_next_tick('orders');  -> 1
select pgque.ticker();                   -> 1
select * from pgque.receive('orders','processor',100);
 msg_id | batch_id |  type   |             payload              | retry_count
      1 |        1 | default | {"total": 99.95, "order_id": 42} |   (null)

retry_count null on first delivery; jsonb canonicalized (total before order_id) exactly as the doc says.

ack via \gset (step 6) — returns 1, then receive returns 0 rows:

select batch_id from pgque.receive('orders','processor',100) limit 1 \gset
select pgque.ack(:batch_id);  -> 1
select * from pgque.receive('orders','processor',100);  -> (0 rows)

nack + retry_count (step 7) — same msg_id, new batch_id, retry_count=1:

do $$ ... nack(...,'0 seconds','simulated failure'); ack(...); $$;
select pgque.maint_retry_events();  -> 1
select pgque.force_next_tick('orders'); select pgque.ticker();
 msg_id | batch_id |  type   |             payload              | retry_count
   2003 |        3 | default | {"total": 10.00, "order_id": 43} |     1

DLQ drive (step 8, max_retries=2, two nack iterations) — message dead-lettered:

select dl_id, dl_reason, ev_id, ev_retry, ev_data from pgque.dlq_inspect('orders');
 dl_id |   dl_reason   | ev_id | ev_retry |             ev_data
     1 | still failing |  2003 |        2 | {"total": 10.00, "order_id": 43}

dlq_replay(1) → new event id 10010, DLQ row removed (dlq_inspect → 0 rows). dlq_purge('orders','0 seconds') → 0.

Health (step 9) — get_queue_info / get_consumer_info / status all returned as documented (status as superuser). Note: status() showed 8 rows here (no pg_cron unavailable row) because pg_cron IS installed; tutorial's 9-row example is the no-cron scenario. Not a discrepancy — correct behavior.

---

Installation (docs/installation.md) — PASS

pgque.start() registered the 4 pg_cron jobs exactly as documented:

      jobname       |  schedule  |                command                  | database
 pgque_maint        | 30 seconds | ... SELECT pgque.maint()                | postgres
 pgque_retry_events | 30 seconds | ... select pgque.maint_retry_events()   | postgres
 pgque_rotate_step2 | 10 seconds | SELECT pgque.maint_rotate_tables_step2()| postgres
 pgque_ticker       | 1 second   | CALL pgque.ticker_loop()                | postgres

status() flipped to scheduler=pg_cron, ticker=scheduled (job_id=1), maintenance=scheduled.

Auto-delivery verified: sent an event with NO manual tick; after ~4 s the cron ticker materialized a batch and receive returned it. cron.job_run_details: jobid 1 (ticker_loop) 19 succeeded, jobid 4 (rotate_step2) succeeded.

Roles & grants — denials all correct:

app_writer -> receive  : ERROR: permission denied for function receive
app_reader -> send     : ERROR: permission denied for function send
app_writer -> send     : 10012 (ok)
app_reader -> version  : 0.2.0 (ok)
app_reader -> create_queue : ERROR: permission denied for function create_queue
app_admin  -> uninstall    : ERROR: permission denied for function uninstall

---

Examples (docs/examples.md) — PASS

Fan-out — one send delivered to 3 independent consumers, same msg_id 10013 via each cursor. Exactly-once wrapped txn (receive+insert+ack) committed atomically, row landed in processed_orders. WRONG snapshot demo (send+tick+receive in one txn) → 0 rows, exactly as documented. send_batch → {16019,16020,16021}; empty array → {}.

---

Monitoring (docs/monitoring.md) — DISCREPANCY (see below)

get_consumer_info (SECURITY DEFINER) works as pgque_reader. dead_letter depth query works as reader. status() correctly denied to reader (admin-only, as documented). BUT get_queue_info fails for pgque_reader — see Discrepancy 1.

get_batch_info (superuser) PASS:

 queue_name | consumer_name |       lag       | seq_start | seq_end
 orders     | audit_logger  | 00:14:19.669091 |     10012 |   12014

---

Reference (docs/reference.md) — PASS (signatures), 1 grant discrepancy

All key signatures/returns verified against pg_proc and match the doc verbatim: receive, ack, nack (incl. defaults '60 seconds'/null), subscribe/unsubscribe, create_queue, drop_queue (1+2 arg), set_queue_config, set_tick_period_ms, start/stop/status/version, dlq_replay→bigint, dlq_replay_all→record(replayed bigint, failed bigint, first_error text), dlq_purge, dlq_inspect→setof pgque.dead_letter, force_next_tick/force_tick, all 4 send_batch overloads, ticker (0/1/4-arg, external-ticker overload present). set_tick_period_ms(50) ok, set_tick_period_ms(7) → "must be an exact divisor of 1000…" as documented.

---

DISCREPANCIES

Discrepancy 1 (functional, reproducible) — pgque.get_queue_info() is unusable by pgque_reader

reference.md documents get_queue_info()/get_queue_info(text) with Grant: pgque_reader, and monitoring.md states "All of the get_*_info functions … are granted to pgque_reader, so a read-only monitoring role can run everything here" — and ships reader queries built on get_queue_info() (the at-a-glance query and the stuck-consumer join).

Reality: a pure pgque_reader session fails at runtime:

set role app_reader;
select queue_name, ev_new from pgque.get_queue_info('orders');
ERROR:  permission denied for function seq_getval
CONTEXT:  PL/pgSQL function pgque.get_queue_info(text) line 58 at assignment

The stuck-consumer join query in monitoring.md (get_consumer_info() c join get_queue_info() q) fails the same way.

Root cause confirmed via catalogs:

• get_queue_info is SECURITY INVOKER (prosecdef = f), unlike get_consumer_info which is SECURITY DEFINER (t) and works fine for the reader.
• Internally get_queue_info calls pgque.seq_getval(text), whose ACL is {postgres=X, pgque_admin=X} — pgque_reader is not granted EXECUTE.
• has_function_privilege('pgque_reader','pgque.get_queue_info(text)','execute') = t (the reader CAN execute the wrapper) but the inner seq_getval call is denied, so the function aborts for any caller that is reader-only.

Effect: works for superuser and for pgque_admin (admin has seq_getval), but not for a read-only monitoring role — directly contradicting both reference.md and monitoring.md. Fix options: make get_queue_info SECURITY DEFINER (like get_consumer_info), or grant EXECUTE on seq_getval to pgque_reader.

---

VERDICT

• Commands/snippets run: ~50 across 6 docs (tutorial, installation, examples, monitoring, reference, plus tick/batch helpers).
• PASS: 5 doc areas (tutorial, installation incl. pg_cron auto-delivery + role denials, examples, reference signatures, lifecycle/tick helpers).
• DISCREPANCY: 1 — pgque.get_queue_info() is documented as reader-callable but fails for pgque_reader with permission denied for function seq_getval (SECURITY INVOKER + missing seq_getval grant). Affects reference.md and monitoring.md, including a shipped monitoring query.
• No PG18-specific surprises with xid8/pg_snapshot; snapshot-isolation behavior (empty-receive-before-tick, WRONG-in-one-txn → 0 rows) held exactly as documented.

[NikolayS]

Fix opened in #267.

Root cause confirmed: get_queue_info(text) ships as SECURITY INVOKER but calls the admin-only pgque.seq_getval(text), so the pgque_reader role it is granted to fails at runtime. The PR promotes both get_queue_info overloads to SECURITY DEFINER with set search_path = pgque, pg_catalog, matching the sibling get_consumer_info / get_batch_info. Includes a failing-first regression test (tests/test_get_queue_info_reader.sql) that exercises both overloads under set role pgque_reader, plus the regenerated single-file installs.