pgmq-ruby 0.7.1 → 0.8.0

data/lib/pgmq/client/multi_queue.rb

@@ -17,6 +17,8 @@ module PGMQ
       # @param qty [Integer] max messages to read per queue
       # @param limit [Integer, nil] max total messages across all queues (nil = all)
       # @return [Array<PGMQ::Message>] array of messages with queue_name attribute
+      # @raise [PGMQ::Errors::MultiQueueInvalidError] if queue_names is not an Array, is empty or has more than 50
+      #   names
       #
       # @example Read from multiple queues (gets first available from any queue)
       #   msg = client.read_multi(['orders', 'notifications', 'emails'], vt: 30, limit: 1).first
@@ -25,7 +27,7 @@ module PGMQ
       # @example Read up to 5 messages from any of the queues
       #   messages = client.read_multi(['queue1', 'queue2', 'queue3'], vt: 30, qty: 5, limit: 5)
       #   messages.each do |msg|
-      #     puts "Processing #{msg.queue_name}: #{msg.payload}"
+      #     puts "Processing #{msg.queue_name}: #{msg.message}"
       #     client.delete(msg.queue_name, msg.msg_id)
       #   end
       #
@@ -46,9 +48,7 @@ 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
+        MULTI_QUEUE_CONTRACT.validate!({ queue_names: queue_names }, Errors::MultiQueueInvalidError)
 
         # Validate all queue names (prevents SQL injection)
         queue_names.each { |qn| validate_queue_name!(qn) }
@@ -85,6 +85,8 @@ module PGMQ
       # @param max_poll_seconds [Integer] maximum seconds to wait for messages
       # @param poll_interval_ms [Integer] milliseconds between polls
       # @return [Array<PGMQ::Message>] array of messages (empty if timeout)
+      # @raise [PGMQ::Errors::MultiQueueInvalidError] if queue_names is not an Array, is empty or has more than 50
+      #   names
       #
       # @example Wait for first available message from any queue
       #   msg = client.read_multi_with_poll(
@@ -104,7 +106,7 @@ module PGMQ
       #     )
       #
       #     messages.each do |msg|
-      #       process(msg.queue_name, msg.payload)
+      #       process(msg.queue_name, msg.message)
       #       client.delete(msg.queue_name, msg.msg_id)
       #     end
       #   end
@@ -116,9 +118,7 @@ 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
+        MULTI_QUEUE_CONTRACT.validate!({ queue_names: queue_names }, Errors::MultiQueueInvalidError)
 
         start_time = Time.now
         poll_interval_seconds = poll_interval_ms / 1000.0
@@ -147,12 +147,14 @@ module PGMQ
       #
       # @param queue_names [Array<String>] array of queue names
       # @return [PGMQ::Message, nil] message with queue_name attribute, or nil if no messages
+      # @raise [PGMQ::Errors::MultiQueueInvalidError] if queue_names is not an Array, is empty or has more than 50
+      #   names
       #
       # @example Get first available message from any queue and auto-delete
       #   msg = client.pop_multi(['orders', 'notifications', 'emails'])
       #   if msg
       #     puts "Got message from #{msg.queue_name}"
-      #     process(msg.payload)
+      #     process(msg.message)
       #     # No need to delete - already deleted!
       #   end
       #
@@ -160,12 +162,10 @@ module PGMQ
       #   loop do
       #     msg = client.pop_multi(['queue1', 'queue2', 'queue3'])
       #     break unless msg
-      #     process(msg.queue_name, msg.payload)
+      #     process(msg.queue_name, msg.message)
       #   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
+        MULTI_QUEUE_CONTRACT.validate!({ queue_names: queue_names }, Errors::MultiQueueInvalidError)
 
         # Validate all queue names
         queue_names.each { |qn| validate_queue_name!(qn) }

data/lib/pgmq/client/producer.rb

@@ -12,10 +12,12 @@ module PGMQ
       # @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 [Numeric, Time] delay in seconds before message becomes visible (integer or float),
-      #   or an absolute Time at which the message becomes visible, including ActiveSupport::TimeWithZone
-      #   (PGMQ v1.10.0+)
+      # @param delay [Numeric, Time] delay in seconds before message becomes visible (integer or float;
+      #   a float such as 1.5 needs PGMQ v1.10.0+), or an absolute Time at which the message becomes visible,
+      #   including ActiveSupport::TimeWithZone (PGMQ v1.10.0+)
       # @return [String] message ID as string
+      # @raise [PGMQ::Errors::MessageInvalidError] if message is not a String, or headers is neither a String nor
+      #   nil
       #
       # @example Basic produce
       #   msg_id = client.produce("orders", '{"order_id":123,"total":99.99}')
@@ -44,27 +46,19 @@ module PGMQ
         delay: 0
       )
         validate_queue_name!(queue_name)
+        MESSAGE_CONTRACT.validate!({ message: message, headers: headers }, Errors::MessageInvalidError)
+        delay_sql, delay_value = delay_argument(delay, headers ? 4 : 3)
 
         result = with_connection do |conn|
-          if headers && !delay.is_a?(Numeric)
+          if headers
             conn.exec_params(
-              "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::jsonb, $4::timestamptz)",
-              [queue_name, message, headers, delay.to_time.utc.iso8601(6)]
-            )
-          elsif headers
-            conn.exec_params(
-              "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::jsonb, $4::integer)",
-              [queue_name, message, headers, delay]
-            )
-          elsif !delay.is_a?(Numeric)
-            conn.exec_params(
-              "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::timestamptz)",
-              [queue_name, message, delay.to_time.utc.iso8601(6)]
+              "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::jsonb, #{delay_sql})",
+              [queue_name, message, headers, delay_value]
             )
           else
             conn.exec_params(
-              "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::integer)",
-              [queue_name, message, delay]
+              "SELECT * FROM pgmq.send($1::text, $2::jsonb, #{delay_sql})",
+              [queue_name, message, delay_value]
             )
           end
         end
@@ -77,11 +71,13 @@ module PGMQ
       # @param queue_name [String] name of the queue
       # @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 [Numeric, Time] delay in seconds before messages become visible (integer or float),
-      #   or an absolute Time at which the messages become visible, including ActiveSupport::TimeWithZone
-      #   (PGMQ v1.10.0+)
+      # @param delay [Numeric, Time] delay in seconds before messages become visible (integer or float;
+      #   a float such as 1.5 needs PGMQ v1.10.0+), or an absolute Time at which the messages become visible,
+      #   including ActiveSupport::TimeWithZone (PGMQ v1.10.0+)
       # @return [Array<String>] array of message IDs
-      # @raise [ArgumentError] if headers array length doesn't match messages length
+      # @raise [PGMQ::Errors::MessageInvalidError] if messages is not an Array, headers is neither an Array nor nil,
+      #   headers length doesn't match messages length, a message is not a String, or a header is neither a String
+      #   nor nil
       #
       # @example Basic batch produce
       #   ids = client.produce_batch("orders", [
@@ -107,38 +103,33 @@ module PGMQ
         delay: 0
       )
         validate_queue_name!(queue_name)
+        BATCH_CONTRACT.validate!({ messages: messages, headers: headers }, Errors::MessageInvalidError)
         return [] if messages.empty?
 
-        if headers && headers.length != messages.length
-          raise ArgumentError,
-            "headers array length (#{headers.length}) must match messages array length (#{messages.length})"
+        messages.each_with_index do |message, index|
+          MESSAGE_CONTRACT.validate!(
+            { message: message, headers: headers && headers[index] },
+            Errors::MessageInvalidError,
+            scope: ["messages", index]
+          )
         end
 
         result = with_connection do |conn|
           encoder = PG::TextEncoder::Array.new
           encoded_messages = encoder.encode(messages)
 
-          if headers && !delay.is_a?(Numeric)
-            encoded_headers = encoder.encode(headers)
-            conn.exec_params(
-              "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::jsonb[], $4::timestamptz)",
-              [queue_name, encoded_messages, encoded_headers, delay.to_time.utc.iso8601(6)]
-            )
-          elsif headers
+          delay_sql, delay_value = delay_argument(delay, headers ? 4 : 3)
+
+          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]
-            )
-          elsif !delay.is_a?(Numeric)
-            conn.exec_params(
-              "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::timestamptz)",
-              [queue_name, encoded_messages, delay.to_time.utc.iso8601(6)]
+              "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::jsonb[], #{delay_sql})",
+              [queue_name, encoded_messages, encoded_headers, delay_value]
             )
           else
             conn.exec_params(
-              "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::integer)",
-              [queue_name, encoded_messages, delay]
+              "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], #{delay_sql})",
+              [queue_name, encoded_messages, delay_value]
             )
           end
         end

data/lib/pgmq/client/queue_management.rb

@@ -44,6 +44,9 @@ module PGMQ
       # @param tune_autovacuum [Boolean, Hash] when truthy, tune autovacuum on the new queue's tables after creation.
       #   Pass +true+ for PGMQ-tuned defaults, or a Hash forwarded to {Autovacuum#tune_autovacuum}. Defaults to
       #   +false+. Note: storage parameters are set on the partitioned parent and do not cascade to partitions.
+      # @param premake [Integer, nil] how many partitions pg_partman creates ahead of the current one, for both the
+      #   queue and the archive table. Must be at least 1 (PGMQ raises otherwise). Defaults to +nil+, which uses
+      #   PGMQ's default (4). Requires PGMQ v1.13.0+ when given.
       # @return [Boolean] true if queue was created, false if it already existed
       #
       # @example
@@ -51,20 +54,37 @@ module PGMQ
       #     partition_interval: "daily",
       #     retention_interval: "7 days"
       #   )  # => true
+      #
+      # @example Pre-make more partitions for a high message rate (PGMQ v1.13.0+)
+      #   client.create_partitioned("events",
+      #     partition_interval: "10000",
+      #     retention_interval: "100000",
+      #     premake: 12
+      #   )  # => true
       def create_partitioned(
         queue_name,
         partition_interval: "10000",
         retention_interval: "100000",
-        tune_autovacuum: false
+        tune_autovacuum: false,
+        premake: nil
       )
         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)",
-            [queue_name, partition_interval, retention_interval]
-          )
+
+          if premake.nil?
+            conn.exec_params(
+              "SELECT pgmq.create_partitioned($1::text, $2::text, $3::text)",
+              [queue_name, partition_interval, retention_interval]
+            )
+          else
+            conn.exec_params(
+              "SELECT pgmq.create_partitioned($1::text, $2::text, $3::text, $4::integer)",
+              [queue_name, partition_interval, retention_interval, premake]
+            )
+          end
+
           apply_tune_autovacuum_option(conn, queue_name, tune_autovacuum)
           !existed
         end

data/lib/pgmq/client/topics.rb

@@ -70,7 +70,8 @@ module PGMQ
       # @param routing_key [String] dot-separated routing key (e.g., "orders.new.priority")
       # @param message [String] message as JSON string
       # @param headers [String, nil] optional headers as JSON string
-      # @param delay [Integer] delay in seconds before message becomes visible
+      # @param delay [Numeric] delay in seconds before message becomes visible (integer or float; a float such as
+      #   1.5 needs PGMQ v1.10.0+)
       # @return [Integer] count of queues the message was delivered to
       #
       # @example Basic topic send
@@ -82,6 +83,11 @@ module PGMQ
       #     headers: '{"trace_id":"abc"}',
       #     delay: 30)
       def produce_topic(routing_key, message, headers: nil, delay: 0)
+        # send_topic takes whole seconds only, so a fractional delay goes through send_batch_topic
+        if delay.is_a?(Numeric) && !delay.integer?
+          return produce_batch_topic(routing_key, [message], headers: headers && [headers], delay: delay).size
+        end
+
         result = with_connection do |conn|
           if headers
             conn.exec_params(
@@ -111,10 +117,12 @@ module PGMQ
       # @param routing_key [String] dot-separated routing key
       # @param messages [Array<String>] array of message payloads as JSON strings
       # @param headers [Array<String>, nil] optional array of headers as JSON strings
-      # @param delay [Numeric, Time] delay in seconds before messages become visible (integer or float),
-      #   or an absolute Time at which the messages become visible, including ActiveSupport::TimeWithZone
-      #   (PGMQ v1.10.0+)
+      # @param delay [Numeric, Time] delay in seconds before messages become visible (integer or float;
+      #   a float such as 1.5 needs PGMQ v1.10.0+), or an absolute Time at which the messages become visible,
+      #   including ActiveSupport::TimeWithZone (PGMQ v1.10.0+)
       # @return [Array<Hash>] array of hashes with :queue_name and :msg_id
+      # @raise [PGMQ::Errors::MessageInvalidError] if messages is not an Array, headers is neither an Array nor nil,
+      #   or headers length doesn't match messages length
       #
       # @example Batch topic send
       #   results = client.produce_batch_topic("orders.new", [
@@ -123,43 +131,30 @@ module PGMQ
       #   ])
       #   # => [{ queue_name: "new_orders", msg_id: "1" }, ...]
       def produce_batch_topic(routing_key, messages, headers: nil, delay: 0)
+        BATCH_CONTRACT.validate!({ messages: messages, headers: headers }, Errors::MessageInvalidError)
         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
-
         result = with_connection do |conn|
           encoder = PG::TextEncoder::Array.new
           encoded_messages = encoder.encode(messages)
 
-          if headers && !delay.is_a?(Numeric)
-            encoded_headers = encoder.encode(headers)
-            conn.exec_params(
-              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::jsonb[], $4::timestamptz)",
-              [routing_key, encoded_messages, encoded_headers, delay.to_time.utc.iso8601(6)]
-            )
-          elsif headers
+          delay_sql, delay_value = delay_argument(delay, headers ? 4 : 3)
+
+          if headers
             encoded_headers = encoder.encode(headers)
             conn.exec_params(
-              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::jsonb[], $4::integer)",
-              [routing_key, encoded_messages, encoded_headers, delay]
-            )
-          elsif !delay.is_a?(Numeric)
-            conn.exec_params(
-              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::timestamptz)",
-              [routing_key, encoded_messages, delay.to_time.utc.iso8601(6)]
+              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::jsonb[], #{delay_sql})",
+              [routing_key, encoded_messages, encoded_headers, delay_value]
             )
-          elsif delay > 0
+          elsif delay.is_a?(Integer) && delay <= 0
             conn.exec_params(
-              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::integer)",
-              [routing_key, encoded_messages, delay]
+              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[])",
+              [routing_key, encoded_messages]
             )
           else
             conn.exec_params(
-              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[])",
-              [routing_key, encoded_messages]
+              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], #{delay_sql})",
+              [routing_key, encoded_messages, delay_value]
             )
           end
         end

data/lib/pgmq/client.rb

@@ -24,6 +24,17 @@ module PGMQ
   # @example With connection string
   #   client = PGMQ::Client.new('postgres://localhost/mydb')
   class Client
+    # Validates message and headers types before they are bound
+    MESSAGE_CONTRACT = Contracts::Message.new
+
+    # Validates the messages and headers arrays of a batch
+    BATCH_CONTRACT = Contracts::Batch.new
+
+    # Validates the arguments of multi-queue operations
+    MULTI_QUEUE_CONTRACT = Contracts::MultiQueue.new
+
+    private_constant :MESSAGE_CONTRACT, :BATCH_CONTRACT, :MULTI_QUEUE_CONTRACT
+
     # Include functional modules (order matters for discoverability)
     include Transaction          # Transaction support (already existed)
     include QueueManagement      # Queue lifecycle (create, drop, list)
@@ -84,11 +95,10 @@ module PGMQ
       @connection.close
     end
 
-    # Drops every pooled connection and rebuilds lazily on the next checkout,
-    # leaving the pool usable (unlike {#close}). Use it to discard a connection
-    # that reports +CONNECTION_OK+ but is actually wedged — e.g. after a
-    # wall-clock timeout interrupted a query mid-flight and left the socket
-    # poisoned so it would re-hang on reuse. See {PGMQ::Connection#reload}.
+    # Drops every pooled connection and rebuilds lazily on the next checkout, leaving the pool usable (unlike {#close}).
+    # Use it to discard a connection that reports +CONNECTION_OK+ but is actually wedged - e.g. after a wall-clock
+    # timeout interrupted a query mid-flight and left the socket poisoned so it would re-hang on reuse. See
+    # {PGMQ::Connection#reload}.
     #
     # @return [void]
     def reload
@@ -118,7 +128,8 @@ module PGMQ
     #
     # @yield [PG::Connection] a pooled, health-checked database connection
     # @return [Object] the return value of the block
-    # @raise [PGMQ::Errors::ConnectionError] if a connection cannot be obtained
+    # @raise [PGMQ::Errors::ConnectionError] if the block raises any `PG::Error` (the original is in `#cause`), or a
+    #   connection cannot be obtained
     #
     # @example Fire a custom NOTIFY on the PGMQ pool
     #   client.with_connection do |conn|
@@ -161,5 +172,25 @@ module PGMQ
       QueueName.validate!(queue_name)
       nil
     end
+
+    # Builds the SQL argument and bind value for a +delay:+ given in seconds or as an absolute Time
+    #
+    # PostgreSQL rejects a Float such as +1.5+ for an +integer+ bind, so a non-Integer Numeric is passed to the
+    # +timestamptz+ overload as +clock_timestamp()+ plus the delay. This is how PGMQ itself turns an integer delay
+    # into a visibility time, so the database clock is used in both cases.
+    #
+    # @param delay [Numeric, Time] delay in seconds or an absolute Time
+    # @param index [Integer] position of the delay bind parameter in the query
+    # @return [Array(String, Object)] SQL argument and its bind value
+    def delay_argument(delay, index)
+      case delay
+      when Integer
+        ["$#{index}::integer", delay]
+      when Numeric
+        ["clock_timestamp() + make_interval(secs => $#{index}::double precision)", delay.to_f]
+      else
+        ["$#{index}::timestamptz", delay.to_time.utc.iso8601(6)]
+      end
+    end
   end
 end

data/lib/pgmq/connection.rb

@@ -26,6 +26,11 @@ module PGMQ
     # Default connection pool timeout in seconds
     DEFAULT_POOL_TIMEOUT = 5
 
+    # Validates the connection configuration
+    CONTRACT = Contracts::Connection.new
+
+    private_constant :CONTRACT
+
     class << self
       # Additional error message patterns (String or Regexp) that mean the connection is dead and a retry on a fresh
       # socket is safe. Strings are matched as case-insensitive substrings; Regexps match the original message. The
@@ -35,8 +40,10 @@ module PGMQ
       #
       # @return [Array<String, Regexp>]
       # @example
-      #   PGMQ::Connection.reconnectable_error_patterns << "connection reset by peer"
-      #   PGMQ::Connection.reconnectable_error_patterns << /\Abroken pipe\b/i
+      #   PGMQ::Connection.reconnectable_error_patterns = [
+      #     "connection reset by peer",
+      #     /\Abroken pipe\b/i
+      #   ]
       attr_reader :reconnectable_error_patterns
 
       # Additional exception classes that mean the connection is dead. `PG::ConnectionBad` and `PG::UnableToSend` are
@@ -46,7 +53,7 @@ module PGMQ
       #
       # @return [Array<Class>]
       # @example
-      #   PGMQ::Connection.reconnectable_error_classes << PG::ConnectionRefused
+      #   PGMQ::Connection.reconnectable_error_classes = [PG::ConnectionRefused]
       attr_reader :reconnectable_error_classes
 
       # Replaces the extra reconnectable error patterns.
@@ -54,6 +61,8 @@ module PGMQ
       # @param patterns [Array<String, Regexp>]
       # @raise [PGMQ::Errors::ConfigurationError] if any element is invalid
       def reconnectable_error_patterns=(patterns)
+        CONTRACT.validate!({ reconnectable_error_patterns: patterns }, Errors::ConfigurationError)
+
         @reconnectable_error_patterns = normalize_patterns(patterns)
       end
 
@@ -62,7 +71,9 @@ module PGMQ
       # @param classes [Array<Class>]
       # @raise [PGMQ::Errors::ConfigurationError] if any element is invalid
       def reconnectable_error_classes=(classes)
-        @reconnectable_error_classes = normalize_classes(classes)
+        CONTRACT.validate!({ reconnectable_error_classes: classes }, Errors::ConfigurationError)
+
+        @reconnectable_error_classes = Array(classes).dup.freeze
       end
 
       private
@@ -75,40 +86,11 @@ module PGMQ
       # @param patterns [Array<String, Regexp>, String, Regexp, nil]
       # @return [Array<String, Regexp>]
       def normalize_patterns(patterns)
-        Array(patterns).map do |pattern|
-          case pattern
-          when Regexp
-            pattern
-          when String
-            pattern.downcase
-          else
-            raise(
-              PGMQ::Errors::ConfigurationError,
-              "reconnectable_error_patterns must contain Strings or Regexps, got #{pattern.class}"
-            )
-          end
-        end.freeze
-      end
-
-      # Normalizes user-supplied reconnectable error classes.
-      #
-      # @param classes [Array<Class>, Class, nil]
-      # @return [Array<Class>]
-      def normalize_classes(classes)
-        Array(classes).map do |klass|
-          unless klass.is_a?(Class) && klass <= Exception
-            raise(
-              PGMQ::Errors::ConfigurationError,
-              "reconnectable_error_classes must contain Exception subclasses, got #{klass.inspect}"
-            )
-          end
-
-          klass
-        end.freeze
+        Array(patterns).map { |pattern| pattern.is_a?(String) ? pattern.downcase : pattern }.freeze
       end
     end
 
-    # Initialize class-level defaults (empty arrays, users append at boot)
+    # Initialize class-level defaults (empty frozen arrays, users replace them at boot via the setters)
     @reconnectable_error_patterns = [].freeze
     @reconnectable_error_classes = [].freeze
 
@@ -128,12 +110,7 @@ module PGMQ
       pool_timeout: DEFAULT_POOL_TIMEOUT,
       auto_reconnect: true
     )
-      if conn_params.nil?
-        raise(
-          PGMQ::Errors::ConfigurationError,
-          "Connection parameters are required"
-        )
-      end
+      CONTRACT.validate!({ conn_params: conn_params }, Errors::ConfigurationError)
 
       @conn_params = normalize_connection_params(conn_params)
       @pool_size = pool_size
@@ -146,7 +123,8 @@ module PGMQ
     #
     # @yield [PG::Connection] database connection
     # @return [Object] result of the block
-    # @raise [PGMQ::Errors::ConnectionError] if connection fails
+    # @raise [PGMQ::Errors::ConnectionError] if the block raises any `PG::Error` (the original is in `#cause`), or a
+    #   connection cannot be obtained
     def with_connection
       retries = @auto_reconnect ? 1 : 0
       attempts = 0
@@ -178,16 +156,13 @@ module PGMQ
       @pool.shutdown { |conn| conn.close unless conn.finished? }
     end
 
-    # Drops every connection currently in the pool and lets the pool build fresh
-    # ones lazily on the next checkout. Unlike {#close} (which shuts the pool
-    # down permanently), the pool stays usable afterwards.
+    # Drops every connection currently in the pool and lets the pool build fresh ones lazily on the next checkout.
+    # Unlike {#close} (which shuts the pool down permanently), the pool stays usable afterwards.
     #
-    # Use this to recover from a connection that libpq still reports as
-    # +CONNECTION_OK+ but which is in fact wedged — e.g. after a wall-clock
-    # timeout (+Timeout.timeout+) interrupted a query mid-flight, leaving the
-    # socket poisoned so it re-hangs on reuse. {#verify_connection!} cannot catch
-    # that case (the connection does not report +CONNECTION_BAD+), so the caller
-    # must discard it explicitly; +reload+ is the safe, pool-wide way to do so.
+    # Use this to recover from a connection that libpq still reports as +CONNECTION_OK+ but which is in fact wedged -
+    # e.g. after a wall-clock timeout (+Timeout.timeout+) interrupted a query mid-flight, leaving the socket poisoned so
+    # it re-hangs on reuse. {#verify_connection!} cannot catch that case (the connection does not report
+    # +CONNECTION_BAD+), so the caller must discard it explicitly; +reload+ is the safe, pool-wide way to do so.
     #
     # @return [void]
     # @example Discard the pool after a query had to be force-interrupted
@@ -281,13 +256,11 @@ module PGMQ
     # Normalizes various connection parameter formats
     # @param params [String, Hash, Proc]
     # @return [Hash, Proc]
-    # @raise [PGMQ::Errors::ConfigurationError] if params format is invalid
+    # @raise [PGMQ::Errors::ConfigurationError] if the connection string is invalid
     def normalize_connection_params(params)
-      return params if params.respond_to?(:call) # Callable (e.g., proc for Rails)
       return parse_connection_string(params) if params.is_a?(String)
-      return params if params.is_a?(Hash) && !params.empty?
 
-      raise PGMQ::Errors::ConfigurationError, "Invalid connection parameters format"
+      params
     end
 
     # Parses a PostgreSQL connection string