pgque 0.3.0.rc.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e9f672944ce942abdda5d3f3dc31588d93854451cceff22471fc47bc7c3cb066
+  data.tar.gz: dd9660e4c51a94356eb9dbdb43c3593ca2be1170b40eb416303a2eddca11cd79
+SHA512:
+  metadata.gz: 1f035242e640be5abb50f1a00bca4cd4bc18f3bb71aaac921f9d42fca47aa2f292bba44c5767218971a3004499a3c816ad0a282d37ca8f2bdd3ca5145289c6f9
+  data.tar.gz: 0c2b7d8c2993be8d4e59636e4474d97111ca589b916b52de477230a267eb5a1841d4b29d2d99c60b0c7c86b0f9df042de33c01103061300072459ab34154f189

data/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Nikolay Samokhvalov
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,106 @@
+# pgque
+
+Ruby client for [PgQue](https://github.com/NikolayS/pgque) — the PgQ-based
+universal PostgreSQL queue. Thin wrapper over `pgque-api` SQL functions:
+`send`, `receive`, `ack`, `nack`, `force_next_tick`, plus a polling
+`Consumer` with `LISTEN`/`NOTIFY` wakeup.
+
+## Install
+
+```bash
+gem install pgque --pre
+```
+
+`--pre` is required while v0.3.0 is in release-candidate; the latest
+published version is `0.3.0.rc.1`. Pin the exact version if you prefer:
+
+```ruby
+gem "pgque", "0.3.0.rc.1"
+```
+
+Requires Ruby 3.1+ and PostgreSQL 14+ with the PgQue schema installed
+(`\i pgque.sql` — no extension required).
+
+## Database permissions
+
+The connecting database role needs `pgque_reader` to consume (`receive`,
+`ack`, `nack`) and `pgque_writer` to produce (`send`, `send_batch`). The
+two are **siblings** — neither inherits the other. An app that both
+produces and consumes must be granted **both** roles:
+
+```sql
+grant pgque_reader to your_app_user;
+grant pgque_writer to your_app_user;
+```
+
+See [`docs/reference.md` — Roles and grants](../../docs/reference.md#roles-and-grants).
+
+## Quickstart
+
+Run the one-time setup once (typically in a migration), then produce
+and consume from any process:
+
+```ruby
+require "pgque"
+
+Pgque.connect("postgresql://localhost/mydb") do |client|
+  # one-time setup
+  client.conn.exec("select pgque.create_queue('orders')")
+  client.conn.exec("select pgque.subscribe('orders', 'order_worker')")
+
+  # produce
+  client.send("orders", { "order_id" => 42 }, type: "order.created")
+end
+
+# consume (separate process)
+consumer = Pgque::Consumer.new(
+  "postgresql://localhost/mydb",
+  queue: "orders",
+  name: "order_worker",
+)
+consumer.on("order.created") { |msg| process_order(msg.payload) }
+consumer.start  # blocks until SIGTERM / SIGINT
+```
+
+The consumer only sees events after `pgque.ticker()` has materialized
+a batch. With `pg_cron` available, run `select pgque.start();` once
+to schedule the default 10 ticks/sec. Without `pg_cron`, drive
+ticking from your application or an external scheduler — see the
+project [Installation](https://github.com/NikolayS/pgque#installation)
+section for both paths.
+
+## A note on `Pgque::Client#send`
+
+The producer method is called `send` to mirror the SQL surface
+(`pgque.send(queue, payload)`) and the Python/TS clients. That name
+shadows Ruby's `Object#send`, which is widely used for reflective
+method invocation. This means `client.send(:close)` calls the SQL
+`send`, **not** the `close` method.
+
+Two well-known Ruby escape hatches restore reflective dispatch on a
+`Pgque::Client` instance:
+
+```ruby
+client.__send__(:close)        # canonical "always works" form
+client.public_send(:close)     # safer: respects visibility
+```
+
+Use `__send__` or `public_send` whenever you need to call a method on
+a `Pgque::Client` by name. The Pgque API itself never calls these
+internally.
+
+## Tests
+
+Integration tests require a running PostgreSQL with the PgQue schema
+installed. Set `PGQUE_TEST_DSN` and run rake:
+
+```bash
+PGQUE_TEST_DSN=postgresql://postgres:pgque_test@localhost/pgque_test \
+    bundle exec rake test
+```
+
+Without `PGQUE_TEST_DSN`, the tests skip.
+
+## License
+
+Apache-2.0. Copyright 2026 Nikolay Samokhvalov.

data/lib/pgque/client.rb

@@ -0,0 +1,283 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+# PgQue includes code derived from PgQ (ISC license,
+# Marko Kreen / Skype Technologies OU).
+
+module Pgque
+  # Thin wrapper over the pgque SQL functions.
+  #
+  # Note: Pgque::Client#send mirrors the SQL `pgque.send(queue, payload)`
+  # primitive and the Python/TS client surface. That name shadows
+  # Ruby's Object#send, so use #__send__ or #public_send when you need
+  # to invoke a method on a Pgque::Client instance reflectively.
+  class Client
+    attr_reader :conn
+
+    def self.connect(dsn)
+      conn = PG.connect(dsn)
+      new(conn, owns_conn: true)
+    rescue PG::ConnectionBad => e
+      raise ConnectionError, e.message
+    end
+
+    def initialize(conn, owns_conn: false)
+      @conn = conn
+      @owns_conn = owns_conn
+    end
+
+    def close
+      return unless @owns_conn
+      return if @conn.finished?
+      @conn.close
+    end
+
+    def send(queue, payload, type: "default")
+      if payload.is_a?(Event)
+        type = payload.type
+        payload = payload.payload
+      end
+      encoded = encode_payload(payload)
+      result =
+        if custom_type?(type)
+          @conn.exec_params(
+            "select pgque.send($1, $2, $3::jsonb)",
+            [queue, type, encoded],
+          )
+        else
+          @conn.exec_params(
+            "select pgque.send($1, $2::jsonb)",
+            [queue, encoded],
+          )
+        end
+      integer_scalar(result)
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def send_batch(queue, type, payloads)
+      encoded = payloads.map { |p| encode_payload(p) }
+      array_literal = pg_text_array(encoded)
+      result = @conn.exec_params(
+        "select unnest(pgque.send_batch($1, $2, $3::jsonb[]))",
+        [queue, type, array_literal],
+      )
+      integer_column(result)
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def receive(queue, consumer, max_messages = 100)
+      result = @conn.exec_params(
+        "select * from pgque.receive($1, $2, $3)",
+        [queue, consumer, max_messages],
+      )
+      result.each_row.map { |row| row_to_message(row) }
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def ack(batch_id)
+      result = @conn.exec_params("select pgque.ack($1)", [batch_id])
+      integer_scalar(result)
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def subscribe(queue, consumer)
+      result = @conn.exec_params(
+        "select pgque.subscribe($1, $2)", [queue, consumer]
+      )
+      integer_scalar(result)
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def unsubscribe(queue, consumer)
+      result = @conn.exec_params(
+        "select pgque.unsubscribe($1, $2)", [queue, consumer]
+      )
+      integer_scalar(result)
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def force_next_tick(queue)
+      result = @conn.exec_params("select pgque.force_next_tick($1)", [queue])
+      v = scalar(result)
+      v.nil? || v.empty? ? nil : v.to_i
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def ticker(queue)
+      result = @conn.exec_params("select pgque.ticker($1)", [queue])
+      v = scalar(result)
+      v.nil? || v.empty? ? nil : v.to_i
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def ticker_all
+      result = @conn.exec_params("select pgque.ticker()", [])
+      integer_scalar(result)
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    # Experimental: function names, edge-case behavior, and signatures may
+    # change before the cooperative API is marked stable.
+    def subscribe_subconsumer(queue, consumer, subconsumer)
+      result = @conn.exec_params(
+        "select pgque.subscribe_subconsumer($1, $2, $3)",
+        [queue, consumer, subconsumer],
+      )
+      integer_scalar(result)
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def unsubscribe_subconsumer(queue, consumer, subconsumer, batch_handling: 0)
+      result = @conn.exec_params(
+        "select pgque.unsubscribe_subconsumer($1, $2, $3, $4)",
+        [queue, consumer, subconsumer, batch_handling],
+      )
+      integer_scalar(result)
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def receive_coop(queue, consumer, subconsumer, max_messages: 100,
+                     dead_interval: nil)
+      result = @conn.exec_params(
+        "select * from pgque.receive_coop($1, $2, $3, $4, $5::interval)",
+        [queue, consumer, subconsumer, max_messages, dead_interval],
+      )
+      result.each_row.map { |row| row_to_message(row) }
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def touch_subconsumer(queue, consumer, subconsumer)
+      result = @conn.exec_params(
+        "select pgque.touch_subconsumer($1, $2, $3)",
+        [queue, consumer, subconsumer],
+      )
+      integer_scalar(result)
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    def nack(batch_id, msg, retry_after: 60, reason: nil)
+      payload_str = case msg.payload
+                    when Hash, Array then JSON.dump(msg.payload)
+                    when nil         then "null"
+                    else                  msg.payload.to_s
+                    end
+      created_at_str = format_created_at(msg.created_at)
+
+      @conn.exec_params(
+        "select pgque.nack($1, " \
+        "ROW($2, $3, $4, $5::jsonb, $6, $7, $8, $9, $10, $11)::pgque.message, " \
+        "$12::interval, $13)",
+        [
+          batch_id, msg.msg_id, msg.batch_id, msg.type, payload_str,
+          msg.retry_count, created_at_str,
+          msg.extra1, msg.extra2, msg.extra3, msg.extra4,
+          "#{retry_after} seconds", reason,
+        ],
+      )
+      nil
+    rescue PG::Error => e
+      raise_wrapped_sql_error(e)
+    end
+
+    private
+
+    # Hash/Array: JSON-encoded.
+    # nil: literal "null" so ::jsonb yields JSON null (not SQL NULL).
+    # String: passed through verbatim; caller must supply valid JSON text.
+    # Anything else (Integer, Float, true, false, Symbol, ...): coerced
+    # via #to_s so numerics and booleans round-trip naturally
+    # (42 -> "42", true -> "true"). Symbols and other objects whose
+    # to_s isn't valid JSON will surface a SQL error from the ::jsonb
+    # cast -- callers who care should pre-encode with JSON.dump.
+    def encode_payload(payload)
+      case payload
+      when Hash, Array then JSON.dump(payload)
+      when nil         then "null"
+      when String      then payload
+      else                  payload.to_s
+      end
+    end
+
+    def pg_text_array(strings)
+      escaped = strings.map do |s|
+        inner = s.to_s.gsub('\\') { '\\\\' }.gsub('"') { '\\"' }
+        "\"#{inner}\""
+      end
+      "{#{escaped.join(',')}}"
+    end
+
+    def row_to_message(row)
+      Message.new(
+        msg_id: row[0].to_i,
+        batch_id: row[1].to_i,
+        type: row[2],
+        payload: parse_jsonb(row[3]),
+        retry_count: row[4].nil? ? nil : row[4].to_i,
+        created_at: row[5].nil? ? nil : Time.parse(row[5]),
+        extra1: row[6],
+        extra2: row[7],
+        extra3: row[8],
+        extra4: row[9],
+      )
+    end
+
+    def parse_jsonb(text)
+      return nil if text.nil?
+      JSON.parse(text)
+    rescue JSON::ParserError
+      text
+    end
+
+    def wrap_sql_error(error)
+      msg = error.message.to_s
+      low = msg.downcase
+      if low.include?("queue not found")
+        QueueNotFound.new(msg)
+      elsif low.include?("batch not found")
+        BatchNotFound.new(msg)
+      else
+        Error.new(msg)
+      end
+    end
+
+    def raise_wrapped_sql_error(error)
+      wrapped = wrap_sql_error(error)
+      wrapped.set_backtrace(error.backtrace) if error.backtrace
+      raise wrapped, cause: error
+    end
+
+    def scalar(result)
+      result.getvalue(0, 0)
+    end
+
+    def integer_scalar(result)
+      scalar(result).to_i
+    end
+
+    def integer_column(result)
+      result.column_values(0).map(&:to_i)
+    end
+
+    def custom_type?(type)
+      !type.to_s.empty? && type != "default"
+    end
+
+    def format_created_at(value)
+      case value
+      when Time then value.iso8601(6)
+      else value
+      end
+    end
+  end
+end

data/lib/pgque/consumer.rb

@@ -0,0 +1,273 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+# PgQue includes code derived from PgQ (ISC license,
+# Marko Kreen / Skype Technologies OU).
+
+require "logger"
+
+module Pgque
+  class Consumer
+    DEFAULT_MAX_MESSAGES = 2_147_483_647
+    WAIT_SLICE_SECONDS = 0.5
+
+    attr_reader :dsn, :queue, :name, :poll_interval, :max_messages,
+                :retry_after, :subconsumer, :dead_interval
+
+    attr_accessor :logger
+
+    def initialize(dsn, queue:, name:, poll_interval: 30,
+                   max_messages: DEFAULT_MAX_MESSAGES, retry_after: 60,
+                   unknown_handler_policy: "nack", subconsumer: nil,
+                   dead_interval: nil, logger: nil)
+      @dsn = dsn
+      @queue = queue
+      @name = name
+      @poll_interval = poll_interval
+      @max_messages = max_messages
+      @retry_after = retry_after
+
+      unless ["nack", "ack"].include?(unknown_handler_policy.to_s)
+        raise ArgumentError,
+              "unknown_handler_policy must be 'nack' or 'ack', " \
+              "got #{unknown_handler_policy.inspect}"
+      end
+      @unknown_handler_policy = unknown_handler_policy.to_s
+
+      if dead_interval && subconsumer.nil?
+        raise ArgumentError,
+              "dead_interval is only valid in cooperative mode " \
+              "(set subconsumer:)"
+      end
+      @subconsumer = subconsumer
+      @dead_interval = dead_interval
+
+      @handlers = {}
+      @default_handler = nil
+      # @running is a plain boolean. Ruby integer/boolean assignment
+      # is atomic, and the only cross-thread interactions are the
+      # signal trap and Consumer#stop flipping it false while the
+      # main loop polls running? -- no ordering dependencies, so a
+      # mutex would be overkill (and unsafe to enter from a signal
+      # trap, which raises ThreadError on Mutex#synchronize).
+      @running = false
+      @stop_signum = nil
+      @logger = logger || default_logger
+    end
+
+    def on(event_type, &block)
+      raise ArgumentError, "block required for Consumer#on" unless block
+
+      if event_type == "*"
+        @default_handler = block
+      else
+        @handlers[event_type] = block
+      end
+      block
+    end
+
+    def start
+      @running = true
+      @stop_signum = nil
+
+      in_main_thread = (Thread.current == Thread.main)
+      original_handlers = {}
+
+      # Signal traps run in a restricted context: Mutex#synchronize,
+      # Logger#info, and most blocking code raise ThreadError. Keep
+      # this proc to plain instance-variable writes; the main loop
+      # logs the signal number after waking up.
+      stop_proc = ->(signum) {
+        @stop_signum = signum
+        @running = false
+      }
+
+      if in_main_thread
+        ["TERM", "INT"].each do |sig|
+          original_handlers[sig] = Signal.trap(sig) { stop_proc.call(sig) }
+        end
+      end
+
+      begin
+        conn = PG.connect(@dsn)
+        begin
+          channel = "pgque_#{@queue}"
+          conn.exec("LISTEN #{conn.escape_identifier(channel)}")
+          @logger.info(
+            "consumer #{@name} listening on #{@queue} (poll=#{@poll_interval}s)"
+          )
+
+          while running?
+            poll_once(conn)
+            break unless running?
+            wait_for_notify_or_stop(conn)
+          end
+
+          if @stop_signum
+            @logger.info("received signal #{@stop_signum}, shutting down")
+          end
+        ensure
+          conn.close unless conn.finished?
+        end
+      ensure
+        # Clear running? before logging so callers observing the flag
+        # see "stopped" by the time the log line is written -- and so
+        # an exception during PG.connect, LISTEN, or the poll loop
+        # leaves the consumer in a consistent state instead of a
+        # ghost "running" with no live worker. Plain instance-var
+        # write -- not the trap-context-unsafe pattern.
+        @running = false
+        if in_main_thread
+          original_handlers.each { |sig, h| Signal.trap(sig, h || "DEFAULT") }
+        end
+        @logger.info("consumer #{@name} stopped")
+      end
+    end
+
+    def stop
+      @running = false
+    end
+
+    def running?
+      @running
+    end
+
+    # Public for testability; not part of the stable API.
+    def poll_once(conn)
+      conn.transaction do
+        client = Client.new(conn)
+        msgs =
+          if @subconsumer
+            client.receive_coop(
+              @queue, @name, @subconsumer,
+              max_messages: @max_messages,
+              dead_interval: @dead_interval,
+            )
+          else
+            client.receive(@queue, @name, @max_messages)
+          end
+
+        next if msgs.empty?
+
+        batch_id = msgs[0].batch_id
+        @logger.debug("batch #{batch_id}: #{msgs.size} message(s)")
+
+        nack_failed = dispatch_batch(client, batch_id, msgs)
+
+        next if nack_failed
+
+        rowcount = client.ack(batch_id)
+        if rowcount == 0
+          @logger.warn(
+            "pgque: ack batch #{batch_id} returned 0 -- stale or " \
+            "double ack (batch already finished or not found)",
+          )
+        end
+      end
+    end
+
+    private
+
+    def dispatch_batch(client, batch_id, msgs)
+      nack_failed = false
+      msgs.each do |msg|
+        handler = @handlers[msg.type] || @default_handler
+
+        if handler.nil?
+          if @unknown_handler_policy == "ack"
+            @logger.warn(
+              "no handler for event type=#{msg.type} ev_id=#{msg.msg_id}; " \
+              "acking",
+            )
+            next
+          end
+          @logger.warn(
+            "no handler for event type=#{msg.type} ev_id=#{msg.msg_id}; " \
+            "nacking",
+          )
+          begin
+            client.nack(batch_id, msg, retry_after: @retry_after,
+                        reason: "no handler for type=#{msg.type}")
+          rescue StandardError => e
+            nack_failed = true
+            @logger.error(
+              "nack failed for unhandled msg_id=#{msg.msg_id}: " \
+              "#{e.class}: #{e.message}",
+            )
+          end
+          next
+        end
+
+        begin
+          handler.call(msg)
+        rescue StandardError => e
+          @logger.error(
+            "handler failed for msg_id=#{msg.msg_id}: " \
+            "#{e.class}: #{e.message}",
+          )
+          begin
+            client.nack(batch_id, msg, retry_after: @retry_after)
+          rescue StandardError => e2
+            nack_failed = true
+            @logger.error(
+              "nack failed for msg_id=#{msg.msg_id}: " \
+              "#{e2.class}: #{e2.message}",
+            )
+          end
+        end
+      end
+      nack_failed
+    end
+
+    def wait_for_notify_or_stop(conn)
+      drained = false
+      while conn.notifies
+        drained = true
+      end
+      return if drained
+
+      deadline = monotonic + @poll_interval
+      while running?
+        remaining = deadline - monotonic
+        return if remaining <= 0
+
+        slice = [WAIT_SLICE_SECONDS, remaining].min
+        notification = conn.wait_for_notify(slice)
+        return unless running?
+
+        if notification
+          while conn.notifies
+            # drain any queued notifications
+          end
+          return
+        end
+      end
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # The default logger is effectively silent: it targets $stderr (so
+    # messages never collide with application stdout) and ships at level
+    # FATAL, which the consumer never emits. Set PGQUE_LOG_LEVEL=warn (or
+    # info, debug, error) to see warnings/info from the consumer, or
+    # pass logger: Logger.new(...) to Consumer.new for full control.
+    def default_logger
+      log = Logger.new($stderr)
+      log.progname = "pgque.consumer.#{@name}"
+      log.level = env_log_level || Logger::FATAL
+      log
+    end
+
+    def env_log_level
+      raw = ENV["PGQUE_LOG_LEVEL"]
+      return nil if raw.nil?
+
+      normalized = raw.strip.upcase
+      return nil if normalized.empty?
+
+      Logger.const_get(normalized)
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/pgque/errors.rb

@@ -0,0 +1,13 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+
+module Pgque
+  class Error < StandardError; end
+
+  class ConnectionError < Error; end
+
+  class QueueNotFound < Error; end
+
+  class BatchNotFound < Error; end
+
+  class ConsumerNotFound < Error; end
+end

data/lib/pgque/event.rb

@@ -0,0 +1,13 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+
+module Pgque
+  class Event
+    attr_reader :payload, :type, :extra
+
+    def initialize(payload:, type: "default", extra: {})
+      @payload = payload
+      @type = type
+      @extra = extra
+    end
+  end
+end

data/lib/pgque/message.rb

@@ -0,0 +1,23 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+
+module Pgque
+  class Message
+    attr_reader :msg_id, :batch_id, :type, :payload, :retry_count,
+                :created_at, :extra1, :extra2, :extra3, :extra4
+
+    def initialize(msg_id:, batch_id:, type:, payload:, retry_count:,
+                   created_at:, extra1: nil, extra2: nil, extra3: nil,
+                   extra4: nil)
+      @msg_id = msg_id
+      @batch_id = batch_id
+      @type = type
+      @payload = payload
+      @retry_count = retry_count
+      @created_at = created_at
+      @extra1 = extra1
+      @extra2 = extra2
+      @extra3 = extra3
+      @extra4 = extra4
+    end
+  end
+end

data/lib/pgque/version.rb

@@ -0,0 +1,5 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+
+module Pgque
+  VERSION = "0.3.0.rc.1"
+end

data/lib/pgque.rb

@@ -0,0 +1,35 @@
+# Copyright 2026 Nikolay Samokhvalov. Apache-2.0 license.
+# PgQue includes code derived from PgQ (ISC license,
+# Marko Kreen / Skype Technologies OU).
+
+require "json"
+require "time"
+require "pg"
+
+require "pgque/version"
+require "pgque/errors"
+require "pgque/event"
+require "pgque/message"
+require "pgque/client"
+require "pgque/consumer"
+
+module Pgque
+  # Open a connection and return a Pgque::Client.
+  #
+  # Ruby's pg gem runs each statement in its own implicit transaction
+  # by default -- the equivalent of psycopg's autocommit=True. To group
+  # statements into one transaction, use conn.transaction { ... } on the
+  # underlying PG::Connection (client.conn). There is no autocommit
+  # flag because Ruby pg has no per-connection autocommit attribute to
+  # toggle; transaction control is per-call via the transaction block.
+  def self.connect(dsn)
+    client = Client.connect(dsn)
+    return client unless block_given?
+
+    begin
+      yield client
+    ensure
+      client.close
+    end
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: pgque
+version: !ruby/object:Gem::Version
+  version: 0.3.0.rc.1
+platform: ruby
+authors:
+- Nikolay Samokhvalov
+- Dalto Curvelano Jr
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'Thin Ruby wrapper over the pgque SQL API: send, send_batch, receive,
+  ack, nack, force_next_tick, plus a polling Consumer with LISTEN/NOTIFY wakeup.'
+email:
+- nik@postgres.ai
+- daltojr@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/pgque.rb
+- lib/pgque/client.rb
+- lib/pgque/consumer.rb
+- lib/pgque/errors.rb
+- lib/pgque/event.rb
+- lib/pgque/message.rb
+- lib/pgque/version.rb
+homepage: https://github.com/NikolayS/pgque
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/NikolayS/pgque
+  source_code_uri: https://github.com/NikolayS/pgque
+  bug_tracker_uri: https://github.com/NikolayS/pgque/issues
+  documentation_uri: https://github.com/NikolayS/pgque/blob/main/docs/reference.md
+  changelog_uri: https://github.com/NikolayS/pgque/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Ruby client for PgQue -- PgQ Universal Edition
+test_files: []