pgmq-ruby 0.1.0 → 0.4.0

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

data/lib/pgmq/transaction.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # Low-level transaction support for PGMQ operations
+  #
+  # Provides atomic execution of PGMQ operations within PostgreSQL transactions.
+  # Transactions are a database primitive - this is a thin wrapper around
+  # PostgreSQL's native transaction support.
+  #
+  # This is analogous to rdkafka-ruby providing Kafka transaction support -
+  # it's a protocol/database feature, not a framework abstraction.
+  #
+  # @example Atomic multi-queue operations
+  #   client.transaction do |txn|
+  #     txn.produce("orders", '{"order_id":123}')
+  #     txn.produce("notifications", '{"type":"order_created"}')
+  #   end
+  #
+  # @example Automatic rollback on error
+  #   client.transaction do |txn|
+  #     txn.produce("orders", '{"order_id":123}')
+  #     raise "Error"  # Both operations rolled back
+  #   end
+  module Transaction
+    # Executes PGMQ operations atomically within a database transaction
+    #
+    # Obtains a connection from the pool, starts a transaction, and yields
+    # a client that uses that transaction for all operations.
+    #
+    # @yield [PGMQ::Client] transactional client using the same connection
+    # @return [Object] result of the block
+    # @raise [PGMQ::Errors::ConnectionError] if transaction fails
+    #
+    # @example
+    #   client.transaction do |txn|
+    #     msg_id = txn.produce("queue", '{"data":"test"}')
+    #     txn.delete("queue", msg_id)
+    #   end
+    def transaction
+      @connection.with_connection do |conn|
+        conn.transaction do
+          yield TransactionalClient.new(self, conn)
+        end
+      end
+    rescue PG::Error, StandardError => e
+      raise PGMQ::Errors::ConnectionError, "Transaction failed: #{e.message}"
+    end
+
+    # Minimal wrapper that ensures all operations use the transaction connection
+    #
+    # @private
+    class TransactionalClient
+      # @param parent [PGMQ::Client] parent client instance
+      # @param conn [PG::Connection] transaction connection
+      def initialize(
+        parent,
+        conn
+      )
+        @parent = parent
+        @conn = conn
+      end
+
+      # Forward all method calls to parent, but use our transaction connection
+      # @param method [Symbol] method name
+      # @return [Object] result of method call
+      def method_missing(method, ...)
+        @parent.respond_to?(method, true) ? @parent.__send__(method, ...) : super
+      end
+
+      # Check if method exists on parent
+      # @param method [Symbol] method name
+      # @param include_private [Boolean] include private methods
+      # @return [Boolean] true if method exists
+      def respond_to_missing?(
+        method,
+        include_private = false
+      )
+        @parent.respond_to?(method, include_private) || super
+      end
+
+      # Inject our transaction connection instead of using the pool
+      def with_connection
+        yield @conn
+      end
+
+      # Expose parent's connection (for tests/inspection)
+      def connection
+        @parent.connection
+      end
+    end
+  end
+end

data/lib/pgmq/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # Current version of the pgmq-ruby gem
+  VERSION = '0.4.0'
+end

data/lib/pgmq.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+require 'time'
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  'pgmq' => 'PGMQ'
+)
+loader.setup
+loader.eager_load
+
+# PGMQ - Low-level Ruby client for Postgres Message Queue
+#
+# This is a low-level library providing direct access to PGMQ operations.
+# For higher-level abstractions, job processing, and framework integrations,
+# see pgmq-framework (similar to how rdkafka-ruby relates to Karafka).
+#
+# @example Basic usage
+#   require 'pgmq'
+#
+#   # Create client with connection parameters
+#   client = PGMQ::Client.new(
+#     host: 'localhost',
+#     port: 5432,
+#     dbname: 'mydb',
+#     user: 'postgres',
+#     password: 'postgres'
+#   )
+#
+#   # Or with connection string
+#   client = PGMQ::Client.new('postgres://localhost/mydb')
+#
+#   # Basic queue operations
+#   client.create('orders')
+#   msg_id = client.produce('orders', '{"order_id":123}')
+#   msg = client.read('orders', vt: 30)
+#   client.delete('orders', msg.msg_id)
+#   client.drop_queue('orders')
+module PGMQ
+  class << self
+    # Convenience method to create a new client
+    #
+    # @return [PGMQ::Client] new client instance
+    # @see PGMQ::Client#initialize
+    #
+    # @example
+    #   client = PGMQ.new('postgres://localhost/mydb')
+    def new(*, **)
+      Client.new(*, **)
+    end
+  end
+end

data/pgmq-ruby.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'lib/pgmq/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'pgmq-ruby'
+  spec.version = PGMQ::VERSION
+  spec.authors = ['Maciej Mensfeld']
+  spec.email = ['maciej@mensfeld.pl']
+
+  spec.summary = 'Ruby client for PGMQ (Postgres Message Queue)'
+  spec.description = 'A Ruby driver for PGMQ - a lightweight message queue built on PostgreSQL. ' \
+                     'Like AWS SQS and RSMQ, but on Postgres.'
+  spec.homepage = 'https://github.com/mensfeld/pgmq-ruby'
+  spec.license = 'LGPL-3.0'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/mensfeld/pgmq-ruby'
+  spec.metadata['changelog_uri'] = 'https://github.com/mensfeld/pgmq-ruby/blob/master/CHANGELOG.md'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/mensfeld/pgmq-ruby/issues'
+  spec.metadata['documentation_uri'] = 'https://github.com/mensfeld/pgmq-ruby#readme'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec|examples)/}) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'connection_pool', '~> 2.4'
+  spec.add_dependency 'pg', '~> 1.5'
+  spec.add_dependency 'zeitwerk', '~> 2.6'
+end

data/renovate.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ],
+  "minimumReleaseAge": "7 days",
+  "github-actions": {
+    "enabled": true,
+    "pinDigests": true
+  }
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgmq-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -23,13 +37,60 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
-description: A Ruby driver for PGMQ - a lightweight message queue built on PostgreSQL
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: A Ruby driver for PGMQ - a lightweight message queue built on PostgreSQL.
+  Like AWS SQS and RSMQ, but on Postgres.
 email:
-- contact@karafka.io
+- maciej@mensfeld.pl
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- ".coditsu/ci.yml"
+- ".github/workflows/ci.yml"
+- ".github/workflows/push.yml"
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".yard-lint.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- docker-compose.yml
+- lib/pgmq.rb
+- lib/pgmq/client.rb
+- lib/pgmq/client/consumer.rb
+- lib/pgmq/client/maintenance.rb
+- lib/pgmq/client/message_lifecycle.rb
+- lib/pgmq/client/metrics.rb
+- lib/pgmq/client/multi_queue.rb
+- lib/pgmq/client/producer.rb
+- lib/pgmq/client/queue_management.rb
+- lib/pgmq/connection.rb
+- lib/pgmq/errors.rb
+- lib/pgmq/message.rb
+- lib/pgmq/metrics.rb
+- lib/pgmq/queue_metadata.rb
+- lib/pgmq/transaction.rb
+- lib/pgmq/version.rb
+- pgmq-ruby.gemspec
+- renovate.json
 homepage: https://github.com/mensfeld/pgmq-ruby
 licenses:
 - LGPL-3.0
@@ -38,6 +99,7 @@ metadata:
   source_code_uri: https://github.com/mensfeld/pgmq-ruby
   changelog_uri: https://github.com/mensfeld/pgmq-ruby/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/mensfeld/pgmq-ruby/issues
+  documentation_uri: https://github.com/mensfeld/pgmq-ruby#readme
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -53,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Ruby client for PGMQ (Postgres Message Queue)
 test_files: []