pgmq-ruby 0.3.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,24 +19,55 @@ 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']
+        result[0]["purge_queue"]
       end
 
-      # Detaches the archive table from PGMQ management
+      # Enables PostgreSQL NOTIFY when messages are inserted into a queue
+      #
+      # When enabled, PostgreSQL will send a NOTIFY event on message insert,
+      # allowing clients to use LISTEN instead of polling. The throttle interval
+      # prevents notification storms during high-volume inserts.
+      #
+      # @param queue_name [String] name of the queue
+      # @param throttle_interval_ms [Integer] minimum ms between notifications (default: 250)
+      # @return [void]
+      #
+      # @example Enable with default throttle (250ms)
+      #   client.enable_notify_insert("orders")
+      #
+      # @example Enable with custom throttle (1 second)
+      #   client.enable_notify_insert("orders", throttle_interval_ms: 1000)
+      #
+      # @example Disable throttling (notify on every insert)
+      #   client.enable_notify_insert("orders", throttle_interval_ms: 0)
+      def enable_notify_insert(queue_name, throttle_interval_ms: 250)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params(
+            "SELECT pgmq.enable_notify_insert($1::text, $2::integer)",
+            [queue_name, throttle_interval_ms]
+          )
+        end
+
+        nil
+      end
+
+      # Disables PostgreSQL NOTIFY for a queue
       #
       # @param queue_name [String] name of the queue
       # @return [void]
       #
       # @example
-      #   client.detach_archive("orders")
-      def detach_archive(queue_name)
+      #   client.disable_notify_insert("orders")
+      def disable_notify_insert(queue_name)
         validate_queue_name!(queue_name)
 
         with_connection do |conn|
-          conn.exec_params('SELECT pgmq.detach_archive($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?
@@ -27,6 +27,26 @@ module PGMQ
         Message.new(result[0])
       end
 
+      # Pops multiple messages atomically (atomic read + delete for batch)
+      #
+      # @param queue_name [String] name of the queue
+      # @param qty [Integer] maximum number of messages to pop
+      # @return [Array<PGMQ::Message>] array of message objects (empty if queue is empty)
+      #
+      # @example Pop up to 10 messages
+      #   messages = client.pop_batch("orders", 10)
+      #   messages.each { |msg| process(msg.payload) }
+      def pop_batch(queue_name, qty)
+        validate_queue_name!(queue_name)
+        return [] if qty <= 0
+
+        result = with_connection do |conn|
+          conn.exec_params("SELECT * FROM pgmq.pop($1::text, $2::integer)", [queue_name, qty])
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+
       # Deletes a message from the queue
       #
       # @param queue_name [String] name of the queue
@@ -43,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
@@ -74,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
@@ -103,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
@@ -137,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
@@ -168,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
@@ -189,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
@@ -209,32 +229,129 @@ 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
-      # @return [PGMQ::Message] updated message
+      # @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?
 
         Message.new(result[0])
       end
+
+      # 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 [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 (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?
+
+        result = with_connection do |conn|
+          encoder = PG::TextEncoder::Array.new
+          encoded_array = encoder.encode(msg_ids)
+
+          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) }
+      end
+
+      # Updates visibility timeout for messages across multiple queues in a single transaction
+      #
+      # Efficiently updates visibility timeouts across different queues atomically.
+      # 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 [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
+      #   client.set_vt_multi({
+      #     'orders' => [1, 2, 3],
+      #     'notifications' => [5, 6],
+      #     'emails' => [10]
+      #   }, 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: 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
+        updates.each_key { |qn| validate_queue_name!(qn) }
+
+        transaction do |txn|
+          result = {}
+          updates.each do |queue_name, msg_ids|
+            next if msg_ids.empty?
+
+            updated_messages = txn.set_vt_batch(queue_name, msg_ids, vt: vt)
+            result[queue_name] = updated_messages
+          end
+          result
+        end
+      end
     end
   end
 end

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

@@ -2,78 +2,123 @@
 
 module PGMQ
   class Client
-    # Message sending operations
+    # Message producing operations
     #
-    # This module handles sending messages to queues, both individual messages
+    # This module handles producing messages to queues, both individual messages
     # and batches. Users must serialize messages to JSON strings themselves.
     module Producer
-      # Sends a message to a queue
+      # Produces a message to a queue
       #
       # @param queue_name [String] name of the queue
       # @param message [String] message as JSON string (for PostgreSQL JSONB)
+      # @param headers [String, nil] optional headers as JSON string (for metadata, routing, tracing)
       # @param delay [Integer] delay in seconds before message becomes visible
       # @return [String] message ID as string
       #
-      # @example
-      #   msg_id = client.send("orders", '{"order_id":123,"total":99.99}')
+      # @example Basic produce
+      #   msg_id = client.produce("orders", '{"order_id":123,"total":99.99}')
       #
       # @example With delay
-      #   msg_id = client.send("orders", '{"data":"value"}', delay: 60)
+      #   msg_id = client.produce("orders", '{"data":"value"}', delay: 60)
+      #
+      # @example With headers for routing/tracing
+      #   msg_id = client.produce("orders", '{"order_id":123}',
+      #     headers: '{"trace_id":"abc123","priority":"high"}')
+      #
+      # @example With headers and delay
+      #   msg_id = client.produce("orders", '{"order_id":123}',
+      #     headers: '{"correlation_id":"req-456"}',
+      #     delay: 30)
       #
       # @note Users must serialize to JSON themselves. Higher-level frameworks
       #       should handle serialization.
-      def send(
+      def produce(
         queue_name,
         message,
+        headers: nil,
         delay: 0
       )
         validate_queue_name!(queue_name)
 
         result = with_connection do |conn|
-          conn.exec_params(
-            'SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::integer)',
-            [queue_name, message, delay]
-          )
+          if headers
+            conn.exec_params(
+              "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)",
+              [queue_name, message, delay]
+            )
+          end
         end
 
-        result[0]['send']
+        result[0]["send"]
       end
 
-      # Sends multiple messages to a queue in a batch
+      # Produces multiple messages to a queue in a batch
       #
       # @param queue_name [String] name of the queue
-      # @param messages [Array<Hash>] array of message payloads
+      # @param messages [Array<String>] array of message payloads as JSON strings
+      # @param headers [Array<String>, nil] optional array of headers as JSON strings (must match messages length)
       # @param delay [Integer] delay in seconds before messages become visible
-      # @return [Array<Integer>] array of message IDs
+      # @return [Array<String>] array of message IDs
+      # @raise [ArgumentError] if headers array length doesn't match messages length
       #
-      # @example
-      #   ids = client.send_batch("orders", [
-      #     { order_id: 1 },
-      #     { order_id: 2 },
-      #     { order_id: 3 }
+      # @example Basic batch produce
+      #   ids = client.produce_batch("orders", [
+      #     '{"order_id":1}',
+      #     '{"order_id":2}',
+      #     '{"order_id":3}'
       #   ])
-      def send_batch(
+      #
+      # @example With headers (one per message)
+      #   ids = client.produce_batch("orders",
+      #     ['{"order_id":1}', '{"order_id":2}'],
+      #     headers: ['{"priority":"high"}', '{"priority":"low"}'])
+      #
+      # @example With headers and delay
+      #   ids = client.produce_batch("orders",
+      #     ['{"order_id":1}', '{"order_id":2}'],
+      #     headers: ['{"trace_id":"a"}', '{"trace_id":"b"}'],
+      #     delay: 60)
+      def produce_batch(
         queue_name,
         messages,
+        headers: nil,
         delay: 0
       )
         validate_queue_name!(queue_name)
         return [] if messages.empty?
 
+        if headers && headers.length != messages.length
+          raise ArgumentError,
+            "headers array length (#{headers.length}) must match messages array length (#{messages.length})"
+        end
+
         # Use PostgreSQL array parameter binding for security
         # PG gem will properly encode the array values
         result = with_connection do |conn|
           # Create array encoder for proper PostgreSQL array formatting
           encoder = PG::TextEncoder::Array.new
-          encoded_array = encoder.encode(messages)
+          encoded_messages = encoder.encode(messages)
 
-          conn.exec_params(
-            'SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::integer)',
-            [queue_name, encoded_array, delay]
-          )
+          if headers
+            encoded_headers = encoder.encode(headers)
+            conn.exec_params(
+              "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)",
+              [queue_name, encoded_messages, delay]
+            )
+          end
         end
 
-        result.map { |row| row['send_batch'] }
+        result.map { |row| row["send_batch"] }
       end
     end
   end