liveBook · Manning

Pgmq.read

As explained in Just Use Postgres!

pgmq.read is a pgmq function that retrieves messages while temporarily hiding them from other consumers subject to a visibility timeout.

pgmq.read retrieves messages without deleting them immediately. A visibility timeout temporarily hides each retrieved message from other consumers, then makes it available again if processing fails or remains incomplete. section 11.7.2

pgmq.read(
  queue_name text, vt integer, qty integer, 
  conditional jsonb DEFAULT '{}'::jsonb)

Use queue_name to select the queue, vt to set the visibility window in seconds, qty to choose the number of messages, and conditional to filter JSON payloads. section 11.7.2

Reserve a visitor for two minutes

SELECT msg_id, message, enqueued_at FROM pgmq.read( queue_name => 'visitors_queue', vt => 120, qty => 1 ); The selected visitor disappears from other consumers during the two-minute window. If processing succeeds, archive the message with pgmq.archive; otherwise, let the timeout expire so another consumer can retrieve it. section 11.7.2

The processing flow is:

  • Read one or more messages and temporarily reserve them. section 11.7.2
  • Complete processing and archive the message, or allow visibility to return after failure. section 11.7.2

How Just Use Postgres! covers it

How deep it goes
Explains parameters and execution behavior through a runnable SQL scenario, stopping short of extension internals.
Examples
Uses a driving-license visitor queue, a two-minute timeout, and Noah Bennett’s message to demonstrate retryable processing.
What it assumes
Assumes a created pgmq queue and familiarity with sending messages; teaches visibility-based retrieval from the queue.
What you can do after
Apply pgmq.read to reserve messages, process them, archive successes, and enable retries after consumer failure.
How it connects
Connects message queues with visibility timeouts, message processing, pgmq.pop, pgmq.archive, and JSONB filtering.
Cover of Just Use Postgres!
liveBookmanning.com
Read Just Use Postgres! on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Just Use Postgres!. The section links point to the parts of the book it draws on.