pgmq-ruby 0.1.0 → 0.3.0

data/lib/pgmq/client/producer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Message sending operations
+    #
+    # This module handles sending messages to queues, both individual messages
+    # and batches. Users must serialize messages to JSON strings themselves.
+    module Producer
+      # Sends a message to a queue
+      #
+      # @param queue_name [String] name of the queue
+      # @param message [String] message as JSON string (for PostgreSQL JSONB)
+      # @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 With delay
+      #   msg_id = client.send("orders", '{"data":"value"}', delay: 60)
+      #
+      # @note Users must serialize to JSON themselves. Higher-level frameworks
+      #       should handle serialization.
+      def send(
+        queue_name,
+        message,
+        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]
+          )
+        end
+
+        result[0]['send']
+      end
+
+      # Sends 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 delay [Integer] delay in seconds before messages become visible
+      # @return [Array<Integer>] array of message IDs
+      #
+      # @example
+      #   ids = client.send_batch("orders", [
+      #     { order_id: 1 },
+      #     { order_id: 2 },
+      #     { order_id: 3 }
+      #   ])
+      def send_batch(
+        queue_name,
+        messages,
+        delay: 0
+      )
+        validate_queue_name!(queue_name)
+        return [] if messages.empty?
+
+        # 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)
+
+          conn.exec_params(
+            'SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::integer)',
+            [queue_name, encoded_array, delay]
+          )
+        end
+
+        result.map { |row| row['send_batch'] }
+      end
+    end
+  end
+end

data/lib/pgmq/client/queue_management.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Queue management operations (create, drop, list)
+    #
+    # This module handles all queue lifecycle operations including creating queues
+    # (standard, partitioned, unlogged), dropping queues, and listing existing queues.
+    module QueueManagement
+      # Creates a new queue
+      #
+      # @param queue_name [String] name of the queue to create
+      # @return [void]
+      # @raise [PGMQ::Errors::InvalidQueueNameError] if queue name is invalid
+      # @raise [PGMQ::Errors::ConnectionError] if database operation fails
+      #
+      # @example
+      #   client.create("orders")
+      def create(queue_name)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params('SELECT pgmq.create($1::text)', [queue_name])
+        end
+
+        nil
+      end
+
+      # Creates a partitioned queue
+      #
+      # Requires pg_partman extension to be installed
+      #
+      # @param queue_name [String] name of the queue
+      # @param partition_interval [String] partition interval (e.g., "daily", "10000")
+      # @param retention_interval [String] retention interval (e.g., "7 days", "100000")
+      # @return [void]
+      #
+      # @example
+      #   client.create_partitioned("big_queue",
+      #     partition_interval: "daily",
+      #     retention_interval: "7 days"
+      #   )
+      def create_partitioned(
+        queue_name,
+        partition_interval: '10000',
+        retention_interval: '100000'
+      )
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params(
+            'SELECT pgmq.create_partitioned($1::text, $2::text, $3::text)',
+            [queue_name, partition_interval, retention_interval]
+          )
+        end
+
+        nil
+      end
+
+      # Creates an unlogged queue for higher throughput (no crash recovery)
+      #
+      # @param queue_name [String] name of the queue
+      # @return [void]
+      #
+      # @example
+      #   client.create_unlogged("fast_queue")
+      def create_unlogged(queue_name)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params('SELECT pgmq.create_unlogged($1::text)', [queue_name])
+        end
+
+        nil
+      end
+
+      # Drops a queue and its archive table
+      #
+      # @param queue_name [String] name of the queue to drop
+      # @return [Boolean] true if queue was dropped
+      #
+      # @example
+      #   client.drop_queue("old_queue")
+      def drop_queue(queue_name)
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params('SELECT pgmq.drop_queue($1::text)', [queue_name])
+        end
+
+        return false if result.ntuples.zero?
+
+        result[0]['drop_queue'] == 't'
+      end
+
+      # Lists all queues
+      #
+      # @return [Array<PGMQ::QueueMetadata>] array of queue metadata objects
+      #
+      # @example
+      #   queues = client.list_queues
+      #   queues.each { |q| puts q.queue_name }
+      def list_queues
+        result = with_connection do |conn|
+          conn.exec('SELECT * FROM pgmq.list_queues()')
+        end
+
+        result.map { |row| QueueMetadata.new(row) }
+      end
+    end
+  end
+end

data/lib/pgmq/client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # Low-level client for interacting with PGMQ (Postgres Message Queue)
+  #
+  # This is a thin wrapper around PGMQ SQL functions. For higher-level
+  # abstractions (job processing, retries, Rails integration), use pgmq-framework.
+  #
+  # @example Basic usage
+  #   client = PGMQ::Client.new(
+  #     host: 'localhost',
+  #     dbname: 'mydb',
+  #     user: 'postgres',
+  #     password: 'postgres'
+  #   )
+  #   client.create('my_queue')
+  #   msg_id = client.send('my_queue', { data: 'value' })
+  #   msg = client.read('my_queue', vt: 30)
+  #   client.delete('my_queue', msg.msg_id)
+  #
+  # @example With Rails/ActiveRecord (reuses Rails connection pool)
+  #   client = PGMQ::Client.new(-> { ActiveRecord::Base.connection.raw_connection })
+  #
+  # @example With connection string
+  #   client = PGMQ::Client.new('postgres://localhost/mydb')
+  class Client
+    # Include functional modules (order matters for discoverability)
+    include Transaction          # Transaction support (already existed)
+    include QueueManagement      # Queue lifecycle (create, drop, list)
+    include Producer             # Message sending operations
+    include Consumer             # Single-queue reading operations
+    include MultiQueue           # Multi-queue operations
+    include MessageLifecycle     # Message state transitions (pop, delete, archive)
+    include Maintenance          # Queue maintenance (purge, detach_archive)
+    include Metrics              # Monitoring and metrics
+
+    # Default visibility timeout in seconds
+    DEFAULT_VT = 30
+
+    # @return [PGMQ::Connection] the connection manager
+    attr_reader :connection
+
+    # Creates a new PGMQ client
+    #
+    # @param conn_params [String, Hash, Proc, PGMQ::Connection, nil] connection parameters
+    # @param pool_size [Integer] connection pool size
+    # @param pool_timeout [Integer] connection pool timeout in seconds
+    # @param auto_reconnect [Boolean] automatically reconnect on connection errors (default: true)
+    #
+    # @example Connection string
+    #   client = PGMQ::Client.new('postgres://user:pass@localhost/db')
+    #
+    # @example Connection hash
+    #   client = PGMQ::Client.new(host: 'localhost', dbname: 'mydb', user: 'postgres')
+    #
+    # @example Inject existing connection (for Rails)
+    #   client = PGMQ::Client.new(-> { ActiveRecord::Base.connection.raw_connection })
+    #
+    # @example Disable auto-reconnect
+    #   client = PGMQ::Client.new(auto_reconnect: false)
+    def initialize(
+      conn_params = nil,
+      pool_size: Connection::DEFAULT_POOL_SIZE,
+      pool_timeout: Connection::DEFAULT_POOL_TIMEOUT,
+      auto_reconnect: true
+    )
+      @connection = if conn_params.is_a?(Connection)
+                      conn_params
+                    else
+                      Connection.new(
+                        conn_params,
+                        pool_size: pool_size,
+                        pool_timeout: pool_timeout,
+                        auto_reconnect: auto_reconnect
+                      )
+                    end
+    end
+
+    # Closes all connections in the pool
+    # @return [void]
+    def close
+      @connection.close
+    end
+
+    # Returns connection pool statistics
+    #
+    # @return [Hash] statistics about the connection pool
+    # @example
+    #   stats = client.stats
+    #   # => { size: 5, available: 3 }
+    def stats
+      @connection.stats
+    end
+
+    private
+
+    # Executes a block with a database connection
+    # @yield [PG::Connection] database connection
+    # @return [Object] result of the block
+    def with_connection(&)
+      @connection.with_connection(&)
+    end
+
+    # Validates a queue name
+    # @param queue_name [String] queue name to validate
+    # @return [void]
+    # @raise [PGMQ::Errors::InvalidQueueNameError] if name is invalid
+    def validate_queue_name!(queue_name)
+      if queue_name.nil? || queue_name.to_s.strip.empty?
+        raise(
+          Errors::InvalidQueueNameError,
+          'Queue name cannot be empty'
+        )
+      end
+
+      # PGMQ creates tables with prefixes (pgmq.q_<name>, pgmq.a_<name>)
+      # PostgreSQL has a 63-character limit for identifiers, but PGMQ enforces 48
+      # to account for prefixes and potential suffixes
+      if queue_name.to_s.length >= 48
+        raise(
+          Errors::InvalidQueueNameError,
+          "Queue name '#{queue_name}' exceeds maximum length of 48 characters " \
+          "(current length: #{queue_name.to_s.length})"
+        )
+      end
+
+      # PostgreSQL identifier rules: start with letter or underscore,
+      # contain only letters, digits, underscores
+      return if queue_name.to_s.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/)
+
+      raise(
+        Errors::InvalidQueueNameError,
+        "Invalid queue name '#{queue_name}': must start with a letter or underscore " \
+        'and contain only letters, digits, and underscores'
+      )
+    end
+  end
+end

data/lib/pgmq/connection.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'pg'
+require 'connection_pool'
+
+module PGMQ
+  # Manages database connections for PGMQ
+  #
+  # Supports multiple connection strategies:
+  # - Connection strings
+  # - Hash of connection parameters
+  # - Callable objects (for Rails ActiveRecord integration)
+  #
+  # @example With connection string
+  #   conn = PGMQ::Connection.new("postgres://localhost/mydb")
+  #
+  # @example With connection hash
+  #   conn = PGMQ::Connection.new(host: 'localhost', dbname: 'mydb')
+  #
+  # @example With Rails ActiveRecord (reuses Rails connection pool)
+  #   conn = PGMQ::Connection.new(-> { ActiveRecord::Base.connection.raw_connection })
+  class Connection
+    # Default connection pool size
+    DEFAULT_POOL_SIZE = 5
+
+    # Default connection pool timeout in seconds
+    DEFAULT_POOL_TIMEOUT = 5
+
+    # @return [ConnectionPool] the connection pool
+    attr_reader :pool
+
+    # Creates a new connection manager
+    #
+    # @param conn_params [String, Hash, Proc] connection parameters or callable
+    # @param pool_size [Integer] size of the connection pool
+    # @param pool_timeout [Integer] connection pool timeout in seconds
+    # @param auto_reconnect [Boolean] automatically reconnect on connection errors
+    # @raise [PGMQ::Errors::ConfigurationError] if conn_params is nil or invalid
+    def initialize(
+      conn_params,
+      pool_size: DEFAULT_POOL_SIZE,
+      pool_timeout: DEFAULT_POOL_TIMEOUT,
+      auto_reconnect: true
+    )
+      if conn_params.nil?
+        raise(
+          PGMQ::Errors::ConfigurationError,
+          'Connection parameters are required'
+        )
+      end
+
+      @conn_params = normalize_connection_params(conn_params)
+      @pool_size = pool_size
+      @pool_timeout = pool_timeout
+      @auto_reconnect = auto_reconnect
+      @pool = create_pool
+    end
+
+    # Executes a block with a connection from the pool
+    #
+    # @yield [PG::Connection] database connection
+    # @return [Object] result of the block
+    # @raise [PGMQ::Errors::ConnectionError] if connection fails
+    def with_connection
+      retries = @auto_reconnect ? 1 : 0
+      attempts = 0
+
+      begin
+        @pool.with do |conn|
+          # Health check: verify connection is alive
+          verify_connection!(conn) if @auto_reconnect
+
+          yield conn
+        end
+      rescue PG::Error => e
+        attempts += 1
+
+        # If connection error and auto_reconnect enabled, try once more
+        retry if attempts <= retries && connection_lost_error?(e)
+
+        raise PGMQ::Errors::ConnectionError, "Database connection error: #{e.message}"
+      rescue ConnectionPool::TimeoutError => e
+        raise PGMQ::Errors::ConnectionError, "Connection pool timeout: #{e.message}"
+      rescue ConnectionPool::PoolShuttingDownError => e
+        raise PGMQ::Errors::ConnectionError, "Connection pool is closed: #{e.message}"
+      end
+    end
+
+    # Closes all connections in the pool
+    # @return [void]
+    def close
+      @pool.shutdown { |conn| conn.close unless conn.finished? }
+    end
+
+    # Returns connection pool statistics
+    #
+    # @return [Hash] statistics about the connection pool
+    # @example
+    #   stats = connection.stats
+    #   # => { size: 5, available: 3 }
+    def stats
+      {
+        size: @pool_size,
+        available: @pool.available
+      }
+    end
+
+    private
+
+    # Checks if the error indicates a lost connection
+    # @param error [PG::Error] the error to check
+    # @return [Boolean] true if connection was lost
+    def connection_lost_error?(error)
+      # Common connection lost errors
+      lost_connection_messages = [
+        'server closed the connection',
+        'connection not open',
+        'no connection to the server',
+        'terminating connection',
+        'connection to server was lost',
+        'could not receive data from server'
+      ]
+
+      message = error.message.downcase
+      lost_connection_messages.any? { |pattern| message.include?(pattern) }
+    end
+
+    # Verifies a connection is alive and working
+    # @param conn [PG::Connection] connection to verify
+    # @raise [PG::Error] if connection is not working
+    def verify_connection!(conn)
+      # Quick check - is connection object in bad state?
+      return unless conn.finished?
+
+      # Connection is finished/closed, try to reset it
+      conn.reset
+    end
+
+    # Normalizes various connection parameter formats
+    # @param params [String, Hash, Proc]
+    # @return [Hash, Proc]
+    # @raise [PGMQ::Errors::ConfigurationError] if params format 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'
+    end
+
+    # Parses a PostgreSQL connection string
+    # @param conn_string [String] connection string (e.g., "postgres://user:pass@host/db")
+    # @return [Hash] connection parameters
+    def parse_connection_string(conn_string)
+      # PG::Connection.conninfo_parse is available in pg >= 0.20
+      if PG::Connection.respond_to?(:conninfo_parse)
+        PG::Connection.conninfo_parse(conn_string).each_with_object({}) do |info, hash|
+          hash[info[:keyword].to_sym] = info[:val] if info[:val]
+        end
+      else
+        # Fallback: pass the string directly and let PG handle it
+        { conninfo: conn_string }
+      end
+    rescue PG::Error => e
+      raise PGMQ::Errors::ConfigurationError, "Invalid connection string: #{e.message}"
+    end
+
+    # Creates the connection pool
+    # @return [ConnectionPool]
+    def create_pool
+      params = @conn_params
+
+      ConnectionPool.new(size: @pool_size, timeout: @pool_timeout) do
+        create_connection(params)
+      end
+    rescue StandardError => e
+      raise PGMQ::Errors::ConnectionError, "Failed to create connection pool: #{e.message}"
+    end
+
+    # Creates a single database connection
+    # @param params [Hash, Proc] connection parameters or callable
+    # @return [PG::Connection]
+    def create_connection(params)
+      # If we have a callable (e.g., for Rails), call it to get the connection
+      return params.call if params.respond_to?(:call)
+
+      # Create new connection from parameters
+      # Low-level library: return all values as strings from PostgreSQL
+      # No automatic type conversion - let higher-level frameworks handle parsing
+      # conn.type_map_for_results intentionally NOT set
+      PG.connect(params[:conninfo] || params)
+    rescue PG::Error => e
+      raise PGMQ::Errors::ConnectionError, "Failed to connect to database: #{e.message}"
+    end
+  end
+end

data/lib/pgmq/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # PGMQ errors namespace
+  module Errors
+    # Base error class for all PGMQ errors
+    class BaseError < StandardError; end
+
+    # Raised when connection to PostgreSQL fails or is lost
+    class ConnectionError < BaseError; end
+
+    # Raised when a queue operation is attempted on a non-existent queue
+    class QueueNotFoundError < BaseError; end
+
+    # Raised when a message cannot be found
+    class MessageNotFoundError < BaseError; end
+
+    # Raised when message serialization fails
+    class SerializationError < BaseError; end
+
+    # Raised when message deserialization fails
+    class DeserializationError < BaseError; end
+
+    # Raised when configuration is invalid
+    class ConfigurationError < BaseError; end
+
+    # Raised when an invalid queue name is provided
+    class InvalidQueueNameError < BaseError; end
+  end
+end

data/lib/pgmq/message.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # Represents a message read from a PGMQ queue
+  #
+  # Returns raw values from PostgreSQL without transformation.
+  # Higher-level frameworks should handle parsing, deserialization, etc.
+  #
+  # @example Reading a message (raw values)
+  #   msg = client.read("my_queue", vt: 30)
+  #   puts msg.msg_id         # => "123" (String from PG)
+  #   puts msg.read_ct        # => "1" (String from PG)
+  #   puts msg.enqueued_at    # => "2025-01-15 10:30:00+00" (String from PG)
+  #   puts msg.vt             # => "2025-01-15 10:30:30+00" (String from PG)
+  #   puts msg.message        # => "{\"order_id\":456}" (Raw JSONB string)
+  #   puts msg.headers        # => "{\"trace_id\":\"abc123\"}" (Raw JSONB string, optional)
+  #   puts msg.queue_name     # => "my_queue" (only present for multi-queue operations)
+  class Message < Data.define(
+    :msg_id, :read_ct, :enqueued_at, :vt, :message, :headers, :queue_name
+  )
+    class << self
+      # Creates a new Message from a database row
+      # @param row [Hash] database row from PG result
+      # @return [Message]
+      def new(row, **)
+        # Return raw values as-is from PostgreSQL
+        # No parsing, no deserialization, no transformation
+        # The pg gem returns JSONB as String by default
+        super(
+          msg_id: row['msg_id'],
+          read_ct: row['read_ct'],
+          enqueued_at: row['enqueued_at'],
+          vt: row['vt'],
+          message: row['message'],
+          headers: row['headers'], # JSONB column for metadata (optional)
+          queue_name: row['queue_name'] # nil for single-queue operations
+        )
+      end
+    end
+
+    # Alias for msg_id (common in messaging systems)
+    # @return [String]
+    alias id msg_id
+  end
+end

data/lib/pgmq/metrics.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module PGMQ
+  # Represents metrics for a PGMQ queue
+  #
+  # @example Getting queue metrics
+  #   metrics = client.metrics("my_queue")
+  #   puts metrics.queue_length        # => 42
+  #   puts metrics.oldest_msg_age_sec  # => 3600
+  class Metrics < Data.define(
+    :queue_name,
+    :queue_length,
+    :newest_msg_age_sec,
+    :oldest_msg_age_sec,
+    :total_messages,
+    :scrape_time
+  )
+    class << self
+      # Creates a new Metrics object from a database row
+      # @param row [Hash] database row from PG result
+      # @return [Metrics]
+      def new(row, **)
+        # Return raw values as-is from PostgreSQL
+        super(
+          queue_name: row['queue_name'],
+          queue_length: row['queue_length'],
+          newest_msg_age_sec: row['newest_msg_age_sec'],
+          oldest_msg_age_sec: row['oldest_msg_age_sec'],
+          total_messages: row['total_messages'],
+          scrape_time: row['scrape_time']
+        )
+      end
+    end
+  end
+end

data/lib/pgmq/queue_metadata.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module PGMQ
+  # Represents metadata about a PGMQ queue
+  #
+  # @example Listing queues
+  #   queues = client.list_queues
+  #   queues.each do |q|
+  #     puts "#{q.queue_name} (partitioned: #{q.is_partitioned})"
+  #   end
+  class QueueMetadata < Data.define(:queue_name, :created_at, :is_partitioned, :is_unlogged)
+    class << self
+      # Creates a new QueueMetadata object from a database row
+      # @param row [Hash] database row from PG result
+      # @return [QueueMetadata]
+      def new(row, **)
+        # Return raw values as-is from PostgreSQL
+        super(
+          queue_name: row['queue_name'],
+          created_at: row['created_at'],
+          is_partitioned: row['is_partitioned'],
+          is_unlogged: row['is_unlogged']
+        )
+      end
+    end
+
+    # Alias for is_partitioned
+    # @return [String] 't' or 'f' from PostgreSQL
+    alias partitioned? is_partitioned
+
+    # Alias for is_unlogged
+    # @return [String] 't' or 'f' from PostgreSQL
+    alias unlogged? is_unlogged
+  end
+end