pgmq-ruby 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5648229b33f490f7228d7f9b106fb40939632c6effff094d028d9f7dd5fc045a
-  data.tar.gz: 7a7d0ae6dd7ee59cf329093f4772e8cd8706e25be0e627defca60f3983e96084
+  metadata.gz: c2a31db1ba5a65a0666bb496ae5b54e0a51de5cafe9b92ebf55b432ea309ef44
+  data.tar.gz: cbf292400bff6ca3f34bdb95ff8a7c6910df5da4db3cbabc574c7b3173864523
 SHA512:
-  metadata.gz: 5da9b67730f7c1b58af6be47c2364092988823b2c536e762ca56cc91bd5f27d2d678aef116373c7f0c62fec5037438f30ae0482979c0df3f9414aa3e5f41987a
-  data.tar.gz: 7c892fcc8d30d306670b7dd3fd3a3e3f70f573916b3e6526e0833a59acad85cdd44fcf830fd327ccba6608fe0e30eb072d2adc1bcb287ccc28c388e743cfd19e
+  metadata.gz: 687e92a06cb6fd93f2015390153693fb267faebc7b4bc8c54fd547cfda2ec87a1621e2be47bb9f2ac70c40b1394a854daee85c4d069845b3756c980672fc49c0
+  data.tar.gz: cb4c6c32f6d69e6329dd12fba2e319865087b08994e894ce169e3360595bc59fb425c6b432ca2ee040b13c4367f0b20ccf307f6fadf9b4d9619dbfc3a509f0a4

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.6.1 (2026-04-16)
+
+### Connection Management
+- **[Fix]** `PGMQ::Connection#verify_connection!` now also resets connections whose status is `PG::CONNECTION_BAD`. Previously it only checked `conn.finished?`, which misses connections closed server-side by the database or an intermediate pooler (PgBouncer `server_idle_timeout` / `client_idle_timeout`, admin kill, TCP RST). A pooled connection with a dead socket would survive `verify_connection!` and fail on the next operation with `PQsocket() can't get socket descriptor`.
+- **[Fix]** `PGMQ::Connection#connection_lost_error?` now recognises `"PQsocket() can't get socket descriptor"` (plus `"connection is closed"` / `"connection has been closed"`). This is the exact error the `pg` gem raises from its C extension when the cached libpq socket FD is gone. Without the match, the `auto_reconnect` retry path in `with_connection` skipped this error and producers failed on the first call following a server-side close.
+
+## 0.6.0 (2026-04-02)
+
+### Breaking Changes
+- **[Breaking]** Drop Ruby 3.2 support. Minimum required Ruby version is now 3.3.0.
+
+### Connection Management
+- **[Breaking]** Detect shared `PG::Connection` across pool slots at creation time. When a callable connection factory returns the same `PG::Connection` object to multiple pool slots, concurrent threads corrupt libpq's internal state, causing nil `PG::Result` (`NoMethodError: undefined method 'ntuples' for nil`), segfaults, or wrong data. The pool now tracks connection identity via `ObjectSpace::WeakKeyMap` and raises `PGMQ::Errors::ConfigurationError` immediately with a descriptive error message. WeakKeyMap entries are automatically cleaned up when connections are GC'd. **This change is breaking for configurations that intentionally share a single `PG::Connection` across multiple pool slots. Users must ensure their callable returns a distinct `PG::Connection` per pool slot or configure `pool_size: 1` when reusing a single shared connection.**
+
+### Infrastructure
+- **[Change]** Migrate test framework from RSpec to Minitest/Spec with Mocha for mocking, aligning with the broader Karafka ecosystem conventions.
+- **[Change]** Replace `rubocop-rspec` with `rubocop-minitest` for test linting.
+- **[Change]** Add `bin/integrations` runner script that centralizes integration spec execution. Specs no longer need `require_relative "support/example_helper"` — the runner injects it via `-r` flag. Run all specs with `bin/integrations` or specific ones with `bin/integrations spec/integration/foo_spec.rb`.
+
 ## 0.5.0 (2026-02-24)
 
 ### Breaking Changes
@@ -153,7 +172,7 @@ Initial release of pgmq-ruby - a low-level Ruby client for PGMQ (PostgreSQL Mess
 - [Enhancement] Example scripts demonstrating all features.
 
 ### Dependencies
-- Ruby >= 3.2.0
+- Ruby >= 3.3.0
 - PostgreSQL >= 14 with PGMQ extension
 - `pg` gem (~> 1.5)
 - `connection_pool` gem (~> 2.4)

data/README.md

@@ -877,7 +877,13 @@ bundle install
 docker compose up -d
 
 # Run tests
-bundle exec rspec
+bundle exec rake test
+
+# Run all integration specs
+bin/integrations
+
+# Run a specific integration spec
+bin/integrations spec/integration/basic_produce_consume_spec.rb
 
 # Run console
 bundle exec bin/console

data/lib/pgmq/connection.rb

@@ -111,29 +111,41 @@ module PGMQ
     # @param error [PG::Error] the error to check
     # @return [Boolean] true if connection was lost
     def connection_lost_error?(error)
-      # Common connection lost errors
+      # Common connection lost errors. Include the pg-gem C-extension message
+      # ("PQsocket() can't get socket descriptor") that is raised when the
+      # cached libpq socket descriptor is gone — e.g. after a server-side
+      # close by a connection pooler such as PgBouncer.
       lost_connection_messages = [
         "server closed the connection",
         "connection not open",
+        "connection is closed",
+        "connection has been closed",
         "no connection to the server",
         "terminating connection",
         "connection to server was lost",
-        "could not receive data from server"
+        "could not receive data from server",
+        "pqsocket() can't get socket descriptor"
       ]
 
-      message = error.message.downcase
+      message = error.message.to_s.downcase
       lost_connection_messages.any? { |pattern| message.include?(pattern) }
     end
 
-    # Verifies a connection is alive and working
+    # Verifies a connection is alive and working.
+    #
+    # Also resets when the connection reports `PG::CONNECTION_BAD`, which
+    # happens when the server (or an intermediate pooler such as PgBouncer)
+    # has closed the socket while the client-side `PG::Connection` object
+    # still exists. `#finished?` alone only catches connections closed
+    # explicitly from the client side.
+    #
     # @param conn [PG::Connection] connection to verify
-    # @raise [PG::Error] if connection is not working
+    # @raise [PG::Error] if the reset itself fails
     def verify_connection!(conn)
-      # Quick check - is connection object in bad state?
-      return unless conn.finished?
+      return conn.reset if conn.finished?
+      return conn.reset if conn.status == PG::CONNECTION_BAD
 
-      # Connection is finished/closed, try to reset it
-      conn.reset
+      nil
     end
 
     # Normalizes various connection parameter formats
@@ -169,9 +181,32 @@ module PGMQ
     # @return [ConnectionPool]
     def create_pool
       params = @conn_params
+      seen_connections = ObjectSpace::WeakKeyMap.new
+      seen_mutex = Mutex.new
 
       ConnectionPool.new(size: @pool_size, timeout: @pool_timeout) do
-        create_connection(params)
+        conn = create_connection(params)
+
+        # Detect shared connections: if a callable returns the same PG::Connection
+        # object to multiple pool slots, concurrent use will corrupt libpq state
+        # (nil results, segfaults, wrong data). Fail fast with a clear message.
+        if conn.is_a?(PG::Connection)
+          seen_mutex.synchronize do
+            if seen_connections.key?(conn)
+              raise PGMQ::Errors::ConfigurationError,
+                "Connection callable returned the same PG::Connection object " \
+                "(object_id: #{conn.object_id}) to multiple pool slots. " \
+                "PG::Connection is NOT thread-safe — concurrent use causes nil results, " \
+                "segfaults, and data corruption. Ensure your callable returns a unique " \
+                "PG::Connection instance on each invocation (for example, by calling " \
+                "PG.connect inside the callable)."
+            end
+
+            seen_connections[conn] = true
+          end
+        end
+
+        conn
       end
     rescue => e
       raise PGMQ::Errors::ConnectionError, "Failed to create connection pool: #{e.message}"

data/lib/pgmq/version.rb

@@ -2,5 +2,5 @@
 
 module PGMQ
   # Current version of the pgmq-ruby gem
-  VERSION = "0.5.0"
+  VERSION = "0.6.1"
 end

data/pgmq-ruby.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
                      "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.required_ruby_version = ">= 3.3.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/mensfeld/pgmq-ruby"
@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   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.files = Dir["lib/**/*", "CHANGELOG.md", "LICENSE", "README.md", "pgmq-ruby.gemspec"]
   spec.require_paths = ["lib"]
 
   # Runtime dependencies

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgmq-ruby
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -59,23 +59,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/ci.yml"
-- ".github/workflows/push.yml"
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
-- ".ruby-version"
-- ".yard-lint.yml"
 - CHANGELOG.md
-- CLAUDE.md
-- Gemfile
-- Gemfile.lint
-- Gemfile.lint.lock
-- Gemfile.lock
 - LICENSE
 - README.md
-- Rakefile
-- docker-compose.yml
 - lib/pgmq.rb
 - lib/pgmq/client.rb
 - lib/pgmq/client/consumer.rb
@@ -93,10 +79,7 @@ files:
 - lib/pgmq/queue_metadata.rb
 - lib/pgmq/transaction.rb
 - lib/pgmq/version.rb
-- package-lock.json
-- package.json
 - pgmq-ruby.gemspec
-- renovate.json
 homepage: https://github.com/mensfeld/pgmq-ruby
 licenses:
 - LGPL-3.0
@@ -114,14 +97,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Ruby client for PGMQ (Postgres Message Queue)
 test_files: []

data/.github/workflows/ci.yml

@@ -1,183 +0,0 @@
-name: CI
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-on:
-  pull_request:
-    branches: [ master ]
-  schedule:
-    - cron: '0 1 * * *'
-
-permissions:
-  contents: read
-
-jobs:
-  specs:
-    timeout-minutes: 15
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        ruby:
-          - '4.0.0'
-          - '3.4'
-          - '3.3'
-          - '3.2'
-        postgres:
-          - '14'
-          - '15'
-          - '16'
-          - '17'
-          - '18'
-        include:
-          - ruby: '3.4'
-            postgres: '18'
-            coverage: 'true'
-
-    services:
-      postgres:
-        image: ghcr.io/pgmq/pg${{ matrix.postgres }}-pgmq:latest
-        env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: pgmq_test
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-        ports:
-          - 5433:5432
-
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-        with:
-          fetch-depth: 0
-
-      - name: Install package dependencies
-        run: "[ -e $APT_DEPS ] || sudo apt-get install -y --no-install-recommends postgresql-client"
-
-      - name: Remove Gemfile.lock for Ruby previews
-        if: contains(matrix.ruby, '4.0')
-        run: rm -f Gemfile.lock
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
-        with:
-          ruby-version: ${{ matrix.ruby }}
-          bundler-cache: true
-          bundler: 'latest'
-          self-hosted: false
-
-      - name: Wait for PostgreSQL
-        run: sleep 5
-
-      - name: Install latest bundler
-        run: |
-          gem install bundler --no-document
-          gem update --system --no-document
-          bundle config set without 'tools benchmarks docs'
-
-      - name: Bundle install
-        run: |
-          bundle config set without development
-          bundle install --jobs 4 --retry 3
-
-      - name: Create PGMQ extension
-        env:
-          PGPASSWORD: postgres
-        run: |
-          psql -h localhost -p 5433 -U postgres -d pgmq_test -c "CREATE EXTENSION IF NOT EXISTS pgmq CASCADE;"
-
-      - name: Run all tests
-        env:
-          PG_HOST: localhost
-          PG_PORT: 5433
-          PG_DATABASE: pgmq_test
-          PG_USER: postgres
-          PG_PASSWORD: postgres
-          CI: true
-          GITHUB_COVERAGE: ${{ matrix.coverage }}
-        run: bundle exec rspec
-
-      - name: Run examples
-        env:
-          PG_HOST: localhost
-          PG_PORT: 5433
-          PG_DATABASE: pgmq_test
-          PG_USER: postgres
-          PG_PASSWORD: postgres
-        run: bundle exec rake examples
-
-  yard-lint:
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-    env:
-      BUNDLE_GEMFILE: Gemfile.lint
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-        with:
-          fetch-depth: 0
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
-        with:
-          ruby-version: '4.0.0'
-          bundler-cache: true
-      - name: Run yard-lint
-        run: bundle exec yard-lint lib/
-
-  rubocop:
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    env:
-      BUNDLE_GEMFILE: Gemfile.lint
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-        with:
-          fetch-depth: 0
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
-        with:
-          ruby-version: '4.0.0'
-          bundler-cache: true
-      - name: Run rubocop
-        run: bundle exec rubocop
-
-  lostconf:
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-        with:
-          fetch-depth: 0
-      - name: Set up Node.js
-        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
-        with:
-          node-version: '20'
-          cache: 'npm'
-      - name: Install dependencies
-        run: npm ci
-      - name: Run lostconf
-        run: npx lostconf --fail-on-stale
-
-  ci-success:
-    name: CI Success
-    runs-on: ubuntu-latest
-    if: always()
-    needs:
-      - rubocop
-      - specs
-      - yard-lint
-      - lostconf
-    steps:
-      - name: Check all jobs passed
-        if: |
-          contains(needs.*.result, 'failure') ||
-          contains(needs.*.result, 'cancelled') ||
-          contains(needs.*.result, 'skipped')
-        run: exit 1
-      - run: echo "All CI checks passed!"

data/.github/workflows/push.yml

@@ -1,35 +0,0 @@
-name: Push Gem
-
-on:
-  push:
-    tags:
-      - v*
-
-permissions:
-  contents: read
-
-jobs:
-  push:
-    if: github.repository_owner == 'mensfeld'
-    runs-on: ubuntu-latest
-    environment: deployment
-
-    permissions:
-      contents: write
-      id-token: write
-
-    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-        with:
-          fetch-depth: 0
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@90be1154f987f4dc0fe0dd0feedac9e473aa4ba8 # v1.286.0
-        with:
-          bundler-cache: false
-
-      - name: Bundle install
-        run: |
-          bundle install --jobs 4 --retry 3
-
-      - uses: rubygems/release-gem@1c162a739e8b4cb21a676e97b087e8268d8fc40b # v1.1.2

data/.gitignore

@@ -1,67 +0,0 @@
-*.gem
-*.rbc
-/.config
-/coverage/
-/InstalledFiles
-/pkg/
-/spec/reports/
-/spec/examples.txt
-/test/tmp/
-/test/version_tmp/
-/tmp/
-
-# Used by dotenv library to load environment variables.
-# .env
-
-# Ignore Byebug command history file.
-.byebug_history
-
-## Specific to RubyMotion:
-.dat*
-.repl_history
-build/
-*.bridgesupport
-build-iPhoneOS/
-build-iPhoneSimulator/
-
-## Specific to RubyMotion (use of CocoaPods):
-#
-# We recommend against adding the Pods directory to your .gitignore. However
-# you should judge for yourself, the pros and cons are mentioned at:
-# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
-#
-# vendor/Pods/
-
-## Documentation cache and generated files:
-/.yardoc/
-/_yardoc/
-/doc/
-/rdoc/
-
-## RSpec test status file
-.rspec_status
-
-## Environment normalization:
-/.bundle/
-/vendor/bundle
-/lib/bundler/man/
-
-# for a library or gem, you might want to ignore these files since the code is
-# intended to run in multiple environments; otherwise, check them in:
-# Gemfile.lock
-# .ruby-version
-# .ruby-gemset
-
-# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
-.rvmrc
-
-# Used by RuboCop. Remote config files pulled in from inherit_from directive.
-# .rubocop-https?--*
-
-.DS_Store
-
-## Claude Code settings (user-specific)
-.claude/
-
-## Coditsu configuration (user-specific)
-.coditsu/local.yml

data/.rspec

@@ -1,2 +0,0 @@
---require spec_helper
---exclude-pattern spec/integration/**/*

data/.rubocop.yml

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-plugins:
-  - rubocop-capybara
-  - rubocop-factory_bot
-  - rubocop-performance
-  - rubocop-rspec
-  - rubocop-rspec_rails
-
-inherit_gem:
-  standard: config/base.yml
-  standard-performance: config/base.yml
-  standard-rspec: config/base.yml
-
-AllCops:
-  NewCops: enable
-  TargetRubyVersion: 3.2
-  Include:
-    - "**/*.rb"
-    - "**/*.gemspec"
-    - "**/Gemfile"
-    - "**/Rakefile"
-    - Gemfile.lint
-
-# Disabled departments - not a Rails project, no Capybara/FactoryBot
-Capybara:
-  Enabled: false
-
-FactoryBot:
-  Enabled: false
-
-RSpecRails:
-  Enabled: false
-
-# Layout
-Layout/LineLength:
-  Max: 120
-
-Layout/SpaceInsideHashLiteralBraces:
-  EnforcedStyle: space
-
-# RSpec - exclude integration examples (they use ExampleHelper, not RSpec)
-RSpec:
-  Exclude:
-    - spec/integration/**/*
-
-RSpec/ExampleLength:
-  Enabled: false
-
-RSpec/IndexedLet:
-  Enabled: false
-
-RSpec/MultipleExpectations:
-  Enabled: false
-
-RSpec/MultipleMemoizedHelpers:
-  Max: 20
-
-RSpec/NestedGroups:
-  Max: 4
-
-RSpec/NoExpectationExample:
-  Enabled: false
-
-RSpec/SpecFilePathFormat:
-  Enabled: false

data/.ruby-version

@@ -1 +0,0 @@
-4.0.0