pgmq-ruby 0.4.0 → 0.5.0

data/lib/pgmq/client/consumer.rb

@@ -33,12 +33,12 @@ module PGMQ
         result = with_connection do |conn|
           if conditional.empty?
             conn.exec_params(
-              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)',
+              "SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)",
               [queue_name, vt, 1]
             )
           else
             conn.exec_params(
-              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)',
+              "SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)",
               [queue_name, vt, 1, conditional.to_json]
             )
           end
@@ -82,12 +82,12 @@ module PGMQ
         result = with_connection do |conn|
           if conditional.empty?
             conn.exec_params(
-              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)',
+              "SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)",
               [queue_name, vt, qty]
             )
           else
             conn.exec_params(
-              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)',
+              "SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)",
               [queue_name, vt, qty, conditional.to_json]
             )
           end
@@ -135,12 +135,12 @@ module PGMQ
         result = with_connection do |conn|
           if conditional.empty?
             conn.exec_params(
-              'SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, $4::integer, $5::integer)',
+              "SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, $4::integer, $5::integer)",
               [queue_name, vt, qty, max_poll_seconds, poll_interval_ms]
             )
           else
-            sql = 'SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, ' \
-                  '$4::integer, $5::integer, $6::jsonb)'
+            sql = "SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, " \
+                  "$4::integer, $5::integer, $6::jsonb)"
             conn.exec_params(
               sql,
               [queue_name, vt, qty, max_poll_seconds, poll_interval_ms, conditional.to_json]
@@ -150,6 +150,79 @@ module PGMQ
 
         result.map { |row| Message.new(row) }
       end
+
+      # Reads messages using grouped round-robin ordering
+      #
+      # Messages are grouped by the first key in their JSON payload and returned
+      # in round-robin order across groups. This ensures fair processing when
+      # messages from different entities (users, orders, etc.) are in the queue.
+      #
+      # @param queue_name [String] name of the queue
+      # @param vt [Integer] visibility timeout in seconds
+      # @param qty [Integer] number of messages to read
+      # @return [Array<PGMQ::Message>] array of messages in round-robin order
+      #
+      # @example Fair processing across users
+      #   # Queue contains: user1_msg1, user1_msg2, user2_msg1, user3_msg1
+      #   messages = client.read_grouped_rr("tasks", vt: 30, qty: 4)
+      #   # Returns in round-robin: user1_msg1, user2_msg1, user3_msg1, user1_msg2
+      #
+      # @example Prevent single entity from monopolizing worker
+      #   loop do
+      #     messages = client.read_grouped_rr("orders", vt: 30, qty: 10)
+      #     break if messages.empty?
+      #     messages.each { |msg| process(msg) }
+      #   end
+      def read_grouped_rr(queue_name, vt: DEFAULT_VT, qty: 1)
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params(
+            "SELECT * FROM pgmq.read_grouped_rr($1::text, $2::integer, $3::integer)",
+            [queue_name, vt, qty]
+          )
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+
+      # Reads messages using grouped round-robin with long-polling support
+      #
+      # Combines grouped round-robin ordering with long-polling for efficient
+      # and fair message consumption.
+      #
+      # @param queue_name [String] name of the queue
+      # @param vt [Integer] visibility timeout in seconds
+      # @param qty [Integer] number of messages to read
+      # @param max_poll_seconds [Integer] maximum time to poll in seconds
+      # @param poll_interval_ms [Integer] interval between polls in milliseconds
+      # @return [Array<PGMQ::Message>] array of messages in round-robin order
+      #
+      # @example Long-polling with fair ordering
+      #   messages = client.read_grouped_rr_with_poll("tasks",
+      #     vt: 30,
+      #     qty: 10,
+      #     max_poll_seconds: 5,
+      #     poll_interval_ms: 100
+      #   )
+      def read_grouped_rr_with_poll(
+        queue_name,
+        vt: DEFAULT_VT,
+        qty: 1,
+        max_poll_seconds: 5,
+        poll_interval_ms: 100
+      )
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params(
+            "SELECT * FROM pgmq.read_grouped_rr_with_poll($1::text, $2::integer, $3::integer, $4::integer, $5::integer)",
+            [queue_name, vt, qty, max_poll_seconds, poll_interval_ms]
+          )
+        end
+
+        result.map { |row| Message.new(row) }
+      end
     end
   end
 end

data/lib/pgmq/client/maintenance.rb

@@ -19,27 +19,10 @@ module PGMQ
         validate_queue_name!(queue_name)
 
         result = with_connection do |conn|
-          conn.exec_params('SELECT pgmq.purge_queue($1::text)', [queue_name])
+          conn.exec_params("SELECT pgmq.purge_queue($1::text)", [queue_name])
         end
 
-        result[0]['purge_queue']
-      end
-
-      # Detaches the archive table from PGMQ management
-      #
-      # @param queue_name [String] name of the queue
-      # @return [void]
-      #
-      # @example
-      #   client.detach_archive("orders")
-      def detach_archive(queue_name)
-        validate_queue_name!(queue_name)
-
-        with_connection do |conn|
-          conn.exec_params('SELECT pgmq.detach_archive($1::text)', [queue_name])
-        end
-
-        nil
+        result[0]["purge_queue"]
       end
 
       # Enables PostgreSQL NOTIFY when messages are inserted into a queue
@@ -65,7 +48,7 @@ module PGMQ
 
         with_connection do |conn|
           conn.exec_params(
-            'SELECT pgmq.enable_notify_insert($1::text, $2::integer)',
+            "SELECT pgmq.enable_notify_insert($1::text, $2::integer)",
             [queue_name, throttle_interval_ms]
           )
         end
@@ -84,7 +67,7 @@ module PGMQ
         validate_queue_name!(queue_name)
 
         with_connection do |conn|
-          conn.exec_params('SELECT pgmq.disable_notify_insert($1::text)', [queue_name])
+          conn.exec_params("SELECT pgmq.disable_notify_insert($1::text)", [queue_name])
         end
 
         nil

data/lib/pgmq/client/message_lifecycle.rb

@@ -19,7 +19,7 @@ module PGMQ
         validate_queue_name!(queue_name)
 
         result = with_connection do |conn|
-          conn.exec_params('SELECT * FROM pgmq.pop($1::text)', [queue_name])
+          conn.exec_params("SELECT * FROM pgmq.pop($1::text)", [queue_name])
         end
 
         return nil if result.ntuples.zero?
@@ -41,7 +41,7 @@ module PGMQ
         return [] if qty <= 0
 
         result = with_connection do |conn|
-          conn.exec_params('SELECT * FROM pgmq.pop($1::text, $2::integer)', [queue_name, qty])
+          conn.exec_params("SELECT * FROM pgmq.pop($1::text, $2::integer)", [queue_name, qty])
         end
 
         result.map { |row| Message.new(row) }
@@ -63,14 +63,14 @@ module PGMQ
 
         result = with_connection do |conn|
           conn.exec_params(
-            'SELECT pgmq.delete($1::text, $2::bigint)',
+            "SELECT pgmq.delete($1::text, $2::bigint)",
             [queue_name, msg_id]
           )
         end
 
         return false if result.ntuples.zero?
 
-        result[0]['delete'] == 't'
+        result[0]["delete"] == "t"
       end
 
       # Deletes multiple messages from the queue
@@ -94,12 +94,12 @@ module PGMQ
           encoded_array = encoder.encode(msg_ids)
 
           conn.exec_params(
-            'SELECT * FROM pgmq.delete($1::text, $2::bigint[])',
+            "SELECT * FROM pgmq.delete($1::text, $2::bigint[])",
             [queue_name, encoded_array]
           )
         end
 
-        result.map { |row| row['delete'] }
+        result.map { |row| row["delete"] }
       end
 
       # Deletes specific messages from multiple queues in a single transaction
@@ -123,7 +123,7 @@ module PGMQ
       #   deletions = messages.group_by(&:queue_name).transform_values { |mss| mss.map(&:msg_id) }
       #   client.delete_multi(deletions)
       def delete_multi(deletions)
-        raise ArgumentError, 'deletions must be a hash' unless deletions.is_a?(Hash)
+        raise ArgumentError, "deletions must be a hash" unless deletions.is_a?(Hash)
         return {} if deletions.empty?
 
         # Validate all queue names
@@ -157,14 +157,14 @@ module PGMQ
 
         result = with_connection do |conn|
           conn.exec_params(
-            'SELECT pgmq.archive($1::text, $2::bigint)',
+            "SELECT pgmq.archive($1::text, $2::bigint)",
             [queue_name, msg_id]
           )
         end
 
         return false if result.ntuples.zero?
 
-        result[0]['archive'] == 't'
+        result[0]["archive"] == "t"
       end
 
       # Archives multiple messages
@@ -188,12 +188,12 @@ module PGMQ
           encoded_array = encoder.encode(msg_ids)
 
           conn.exec_params(
-            'SELECT * FROM pgmq.archive($1::text, $2::bigint[])',
+            "SELECT * FROM pgmq.archive($1::text, $2::bigint[])",
             [queue_name, encoded_array]
           )
         end
 
-        result.map { |row| row['archive'] }
+        result.map { |row| row["archive"] }
       end
 
       # Archives specific messages from multiple queues in a single transaction
@@ -209,7 +209,7 @@ module PGMQ
       #     'notifications' => [5]
       #   })
       def archive_multi(archives)
-        raise ArgumentError, 'archives must be a hash' unless archives.is_a?(Hash)
+        raise ArgumentError, "archives must be a hash" unless archives.is_a?(Hash)
         return {} if archives.empty?
 
         # Validate all queue names
@@ -229,26 +229,35 @@ module PGMQ
 
       # Updates the visibility timeout for a message
       #
+      # Supports two modes:
+      # - Integer offset (seconds from now): `vt: 60` - message visible in 60 seconds
+      # - Absolute timestamp: `vt: Time.now + 300` - message visible at specific time
+      #
       # @param queue_name [String] name of the queue
       # @param msg_id [Integer] message ID
-      # @param vt_offset [Integer] visibility timeout offset in seconds
+      # @param vt [Integer, Time] visibility timeout as seconds offset or absolute timestamp
       # @return [PGMQ::Message, nil] updated message or nil if not found
       #
-      # @example
-      #   # Extend processing time by 60 more seconds
-      #   msg = client.set_vt("orders", 123, vt_offset: 60)
-      def set_vt(
-        queue_name,
-        msg_id,
-        vt_offset:
-      )
+      # @example Extend processing time by 60 more seconds (offset)
+      #   msg = client.set_vt("orders", 123, vt: 60)
+      #
+      # @example Set absolute visibility time (timestamp)
+      #   msg = client.set_vt("orders", 123, vt: Time.now + 300)
+      def set_vt(queue_name, msg_id, vt:)
         validate_queue_name!(queue_name)
 
         result = with_connection do |conn|
-          conn.exec_params(
-            'SELECT * FROM pgmq.set_vt($1::text, $2::bigint, $3::integer)',
-            [queue_name, msg_id, vt_offset]
-          )
+          if vt.is_a?(Time)
+            conn.exec_params(
+              "SELECT * FROM pgmq.set_vt($1::text, $2::bigint, $3::timestamptz)",
+              [queue_name, msg_id, vt.utc.iso8601(6)]
+            )
+          else
+            conn.exec_params(
+              "SELECT * FROM pgmq.set_vt($1::text, $2::bigint, $3::integer)",
+              [queue_name, msg_id, vt]
+            )
+          end
         end
 
         return nil if result.ntuples.zero?
@@ -258,19 +267,21 @@ module PGMQ
 
       # Updates visibility timeout for multiple messages
       #
+      # Supports two modes:
+      # - Integer offset (seconds from now): `vt: 60` - messages visible in 60 seconds
+      # - Absolute timestamp: `vt: Time.now + 300` - messages visible at specific time
+      #
       # @param queue_name [String] name of the queue
       # @param msg_ids [Array<Integer>] array of message IDs
-      # @param vt_offset [Integer] visibility timeout offset in seconds
+      # @param vt [Integer, Time] visibility timeout as seconds offset or absolute timestamp
       # @return [Array<PGMQ::Message>] array of updated messages
       #
-      # @example
-      #   # Extend processing time for multiple messages
-      #   messages = client.set_vt_batch("orders", [101, 102, 103], vt_offset: 60)
-      def set_vt_batch(
-        queue_name,
-        msg_ids,
-        vt_offset:
-      )
+      # @example Extend processing time for multiple messages (offset)
+      #   messages = client.set_vt_batch("orders", [101, 102, 103], vt: 60)
+      #
+      # @example Set absolute visibility time (timestamp)
+      #   messages = client.set_vt_batch("orders", [101, 102], vt: Time.now + 300)
+      def set_vt_batch(queue_name, msg_ids, vt:)
         validate_queue_name!(queue_name)
         return [] if msg_ids.empty?
 
@@ -278,10 +289,17 @@ module PGMQ
           encoder = PG::TextEncoder::Array.new
           encoded_array = encoder.encode(msg_ids)
 
-          conn.exec_params(
-            'SELECT * FROM pgmq.set_vt($1::text, $2::bigint[], $3::integer)',
-            [queue_name, encoded_array, vt_offset]
-          )
+          if vt.is_a?(Time)
+            conn.exec_params(
+              "SELECT * FROM pgmq.set_vt($1::text, $2::bigint[], $3::timestamptz)",
+              [queue_name, encoded_array, vt.utc.iso8601(6)]
+            )
+          else
+            conn.exec_params(
+              "SELECT * FROM pgmq.set_vt($1::text, $2::bigint[], $3::integer)",
+              [queue_name, encoded_array, vt]
+            )
+          end
         end
 
         result.map { |row| Message.new(row) }
@@ -293,8 +311,12 @@ module PGMQ
       # Useful when processing related messages from different queues and needing
       # to extend their visibility timeouts together.
       #
+      # Supports two modes:
+      # - Integer offset (seconds from now): `vt: 60` - messages visible in 60 seconds
+      # - Absolute timestamp: `vt: Time.now + 300` - messages visible at specific time
+      #
       # @param updates [Hash] hash of queue_name => array of msg_ids
-      # @param vt_offset [Integer] visibility timeout offset in seconds (applied to all)
+      # @param vt [Integer, Time] visibility timeout as seconds offset or absolute timestamp
       # @return [Hash] hash of queue_name => array of updated PGMQ::Message objects
       #
       # @example Extend visibility timeout for messages from multiple queues
@@ -302,15 +324,18 @@ module PGMQ
       #     'orders' => [1, 2, 3],
       #     'notifications' => [5, 6],
       #     'emails' => [10]
-      #   }, vt_offset: 60)
+      #   }, vt: 60)
       #   # => { 'orders' => [<Message>, ...], 'notifications' => [...], 'emails' => [...] }
       #
+      # @example Set absolute visibility time
+      #   client.set_vt_multi(updates, vt: Time.now + 300)
+      #
       # @example Extend timeout after batch reading from multiple queues
       #   messages = client.read_multi(['q1', 'q2', 'q3'], qty: 10)
       #   updates = messages.group_by(&:queue_name).transform_values { |msgs| msgs.map(&:msg_id) }
-      #   client.set_vt_multi(updates, vt_offset: 120)
-      def set_vt_multi(updates, vt_offset:)
-        raise ArgumentError, 'updates must be a hash' unless updates.is_a?(Hash)
+      #   client.set_vt_multi(updates, vt: 120)
+      def set_vt_multi(updates, vt:)
+        raise ArgumentError, "updates must be a hash" unless updates.is_a?(Hash)
         return {} if updates.empty?
 
         # Validate all queue names
@@ -321,7 +346,7 @@ module PGMQ
           updates.each do |queue_name, msg_ids|
             next if msg_ids.empty?
 
-            updated_messages = txn.set_vt_batch(queue_name, msg_ids, vt_offset: vt_offset)
+            updated_messages = txn.set_vt_batch(queue_name, msg_ids, vt: vt)
             result[queue_name] = updated_messages
           end
           result

data/lib/pgmq/client/metrics.rb

@@ -20,7 +20,7 @@ module PGMQ
         validate_queue_name!(queue_name)
 
         result = with_connection do |conn|
-          conn.exec_params('SELECT * FROM pgmq.metrics($1::text)', [queue_name])
+          conn.exec_params("SELECT * FROM pgmq.metrics($1::text)", [queue_name])
         end
 
         return nil if result.ntuples.zero?
@@ -39,7 +39,7 @@ module PGMQ
       #   end
       def metrics_all
         result = with_connection do |conn|
-          conn.exec('SELECT * FROM pgmq.metrics_all()')
+          conn.exec("SELECT * FROM pgmq.metrics_all()")
         end
 
         result.map { |row| PGMQ::Metrics.new(row) }

data/lib/pgmq/client/multi_queue.rb

@@ -46,9 +46,9 @@ module PGMQ
         qty: 1,
         limit: nil
       )
-        raise ArgumentError, 'queue_names must be an array' unless queue_names.is_a?(Array)
-        raise ArgumentError, 'queue_names cannot be empty' if queue_names.empty?
-        raise ArgumentError, 'queue_names cannot exceed 50 queues' if queue_names.size > 50
+        raise ArgumentError, "queue_names must be an array" unless queue_names.is_a?(Array)
+        raise ArgumentError, "queue_names cannot be empty" if queue_names.empty?
+        raise ArgumentError, "queue_names cannot exceed 50 queues" if queue_names.size > 50
 
         # Validate all queue names (prevents SQL injection)
         queue_names.each { |qn| validate_queue_name!(qn) }
@@ -118,9 +118,9 @@ module PGMQ
         max_poll_seconds: 5,
         poll_interval_ms: 100
       )
-        raise ArgumentError, 'queue_names must be an array' unless queue_names.is_a?(Array)
-        raise ArgumentError, 'queue_names cannot be empty' if queue_names.empty?
-        raise ArgumentError, 'queue_names cannot exceed 50 queues' if queue_names.size > 50
+        raise ArgumentError, "queue_names must be an array" unless queue_names.is_a?(Array)
+        raise ArgumentError, "queue_names cannot be empty" if queue_names.empty?
+        raise ArgumentError, "queue_names cannot exceed 50 queues" if queue_names.size > 50
 
         start_time = Time.now
         poll_interval_seconds = poll_interval_ms / 1000.0
@@ -165,9 +165,9 @@ module PGMQ
       #     process(msg.queue_name, msg.payload)
       #   end
       def pop_multi(queue_names)
-        raise ArgumentError, 'queue_names must be an array' unless queue_names.is_a?(Array)
-        raise ArgumentError, 'queue_names cannot be empty' if queue_names.empty?
-        raise ArgumentError, 'queue_names cannot exceed 50 queues' if queue_names.size > 50
+        raise ArgumentError, "queue_names must be an array" unless queue_names.is_a?(Array)
+        raise ArgumentError, "queue_names cannot be empty" if queue_names.empty?
+        raise ArgumentError, "queue_names cannot exceed 50 queues" if queue_names.size > 50
 
         # Validate all queue names
         queue_names.each { |qn| validate_queue_name!(qn) }

data/lib/pgmq/client/producer.rb

@@ -43,18 +43,18 @@ module PGMQ
         result = with_connection do |conn|
           if headers
             conn.exec_params(
-              'SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::jsonb, $4::integer)',
+              "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::jsonb, $4::integer)",
               [queue_name, message, headers, delay]
             )
           else
             conn.exec_params(
-              'SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::integer)',
+              "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::integer)",
               [queue_name, message, delay]
             )
           end
         end
 
-        result[0]['send']
+        result[0]["send"]
       end
 
       # Produces multiple messages to a queue in a batch
@@ -94,7 +94,7 @@ module PGMQ
 
         if headers && headers.length != messages.length
           raise ArgumentError,
-                "headers array length (#{headers.length}) must match messages array length (#{messages.length})"
+            "headers array length (#{headers.length}) must match messages array length (#{messages.length})"
         end
 
         # Use PostgreSQL array parameter binding for security
@@ -107,18 +107,18 @@ module PGMQ
           if headers
             encoded_headers = encoder.encode(headers)
             conn.exec_params(
-              'SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::jsonb[], $4::integer)',
+              "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::jsonb[], $4::integer)",
               [queue_name, encoded_messages, encoded_headers, delay]
             )
           else
             conn.exec_params(
-              'SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::integer)',
+              "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::integer)",
               [queue_name, encoded_messages, delay]
             )
           end
         end
 
-        result.map { |row| row['send_batch'] }
+        result.map { |row| row["send_batch"] }
       end
     end
   end

data/lib/pgmq/client/queue_management.rb

@@ -22,7 +22,7 @@ module PGMQ
 
         with_connection do |conn|
           existed = queue_exists?(conn, queue_name)
-          conn.exec_params('SELECT pgmq.create($1::text)', [queue_name])
+          conn.exec_params("SELECT pgmq.create($1::text)", [queue_name])
           !existed
         end
       end
@@ -43,15 +43,15 @@ module PGMQ
       #   )  # => true
       def create_partitioned(
         queue_name,
-        partition_interval: '10000',
-        retention_interval: '100000'
+        partition_interval: "10000",
+        retention_interval: "100000"
       )
         validate_queue_name!(queue_name)
 
         with_connection do |conn|
           existed = queue_exists?(conn, queue_name)
           conn.exec_params(
-            'SELECT pgmq.create_partitioned($1::text, $2::text, $3::text)',
+            "SELECT pgmq.create_partitioned($1::text, $2::text, $3::text)",
             [queue_name, partition_interval, retention_interval]
           )
           !existed
@@ -70,7 +70,7 @@ module PGMQ
 
         with_connection do |conn|
           existed = queue_exists?(conn, queue_name)
-          conn.exec_params('SELECT pgmq.create_unlogged($1::text)', [queue_name])
+          conn.exec_params("SELECT pgmq.create_unlogged($1::text)", [queue_name])
           !existed
         end
       end
@@ -86,12 +86,12 @@ module PGMQ
         validate_queue_name!(queue_name)
 
         result = with_connection do |conn|
-          conn.exec_params('SELECT pgmq.drop_queue($1::text)', [queue_name])
+          conn.exec_params("SELECT pgmq.drop_queue($1::text)", [queue_name])
         end
 
         return false if result.ntuples.zero?
 
-        result[0]['drop_queue'] == 't'
+        result[0]["drop_queue"] == "t"
       end
 
       # Lists all queues
@@ -103,7 +103,7 @@ module PGMQ
       #   queues.each { |q| puts q.queue_name }
       def list_queues
         result = with_connection do |conn|
-          conn.exec('SELECT * FROM pgmq.list_queues()')
+          conn.exec("SELECT * FROM pgmq.list_queues()")
         end
 
         result.map { |row| QueueMetadata.new(row) }
@@ -118,7 +118,7 @@ module PGMQ
       # @return [Boolean] true if queue exists, false otherwise
       def queue_exists?(conn, queue_name)
         result = conn.exec_params(
-          'SELECT 1 FROM pgmq.meta WHERE queue_name = $1 LIMIT 1',
+          "SELECT 1 FROM pgmq.meta WHERE queue_name = $1 LIMIT 1",
           [queue_name]
         )
         result.ntuples.positive?