pg_pipeline 0.3.2 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7fdda2e5d806be070a3255e8cef4a63b72acaeac87d7a7777d580bfb0fc0d0a
-  data.tar.gz: 2b23bf8808241eb64396672959a86ae86c26af05bb0d72049de646907cc9e99d
+  metadata.gz: c47c7cb9266d0541b6d57aeba3c25f311f1e8ba6b661c2b79ddc0aea6fe5fe24
+  data.tar.gz: 8c34eae2688944b938ee4adfe2c07ae2730571536ff328dc41368add95667410
 SHA512:
-  metadata.gz: 37a5b065506fb61a675a72023057b0d24254ea7fa411ea358c68e255e0ffabf53079ab3a7214be59b2d09b02063aa2c09875576868a213df8c91526f90834ebd
-  data.tar.gz: fb0e3b15f73e8de66b56d09c7791b8e357477c859b83293474ec48c15d41d12298f91c974bd8ebeb0ae2cc6a3437ed598c442e6eb26e8a13787e71a3d35856f7
+  metadata.gz: a869a0dcfb3a2c8f0eaa9f7f4979ebf71f8af893b3792de15a4db6c8a2f9852f9f7a42474580468cdb3b9cac50f08ec0a2525627551fc731d715b70ac1c3d03c
+  data.tar.gz: ca9179c01ab0a824b07be2923578b51489d91ccd2e9076ba2da44d789f2aef666cffd77d481b85577c0265f8f7bc0f0b33fe028ba535007928bb7489b21c504c

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.3.4] - 2026-10-28
+
+Internal refactoring of the control plane. No intended public API or wire
+behaviour changes.
+
+### Changed
+
+- Centralized pool option defaults and validation.
+- Split driver, pool, request, SQL-guard, and type-map operations into smaller
+  focused methods and removed redundant repeated lookups.
+
+### Fixed
+
+- Readable driver events now trigger result draining.
+
+## [0.3.3] - 2026-08-19
+
+Opt-in typed result decoding for multiplexed prepared statements. Default
+behaviour, Sync-per-unit, and the failure model are unchanged.
+
+### Added
+
+- `Client#prepare(..., typed: true)` — text format. The first `TUPLES_OK`
+  result builds a `TypeMapByColumn`; later dispatches reuse that map from the
+  `Request` (resolved at submit, never re-read from handle state at drain).
+  Column values arrive as typed Ruby objects (Integer, Time, BigDecimal, …)
+  instead of strings, for every PostgreSQL type ruby-pg covers in text mode.
+
+### Notes
+
+- This is an API feature, not a throughput lever. Typed columns that become
+  immediates (`int`, `bool`) drop one heap object each; the rest of the
+  per-query allocation is the control plane (`Request`, fibers, `PG::Result`).
+- `CoderMapsBundle` is built on a throwaway connection at the first
+  `prepare(..., typed: true)`, never at `Client.start` and never on a live
+  pipeline FIFO (a catalog query there desyncs Sync). Untyped `query` /
+  `prepare` do not touch type maps on the drain path.
+- A failed type-map apply is a request-local `QueryError`. `typed: true`
+  promised a typed value; the handle does not silently fall back to strings.
+- `bigdecimal` is an optional dependency of ruby-pg for `numeric` text
+  decoding (required as a gem on Ruby 3.4+). Without it, other typed columns
+  still work; `numeric` follows the registry.
+- Default path (no `typed:`): `TypeMapAllStrings`, text format, string keys.
+- Binary result format is not part of this release.
+
 ## [0.3.2] - 2026-08-17
 
 Runtime correctness. Public SQL, Sync-per-unit, failure model, and the

data/README.md

@@ -143,6 +143,27 @@ ensure
 end
 ```
 
+Pass `typed: true` to decode cells through ruby-pg's text type map (`Integer`,
+`Time`, `BigDecimal`, …) instead of strings. The map is built from the first
+result and reused. This does not change the wire format or the Sync-per-unit
+model; it is opt-in convenience, not a faster path.
+
+```ruby
+by_id = db.prepare(
+  "user_by_id",
+  "SELECT id, email FROM users WHERE id = $1",
+  [23],
+  typed: true
+)
+
+result = by_id.query([42])
+begin
+  result.first["id"] # => 42 (Integer)
+ensure
+  result.clear
+end
+```
+
 `Client#prepare` returns only after the statement is ready on every currently
 live pipeline connection. Replacement connections automatically prepare the
 registered catalog before they begin accepting requests. The logical name is

data/lib/pg_pipeline/bounded_queue.rb

@@ -1,17 +1,19 @@
 # frozen_string_literal: true
 
-require_relative "errors"
-require_relative "runtime"
+require_relative 'errors'
+require_relative 'runtime'
 
 module PgPipeline
   class BoundedQueue
     def initialize(limit)
       @limit = Integer(limit)
-      raise ArgumentError, "limit must be >= 1" if @limit < 1
+      raise ArgumentError, 'limit must be >= 1' if @limit < 1
     rescue ArgumentError, TypeError
-      raise ArgumentError, "limit must be an integer >= 1"
+      raise ArgumentError, 'limit must be an integer >= 1'
     else
-      @items, @consumers, @producers = [], [], []
+      @items = []
+      @consumers = []
+      @producers = []
 
       @closed = false
       @close_error = nil
@@ -93,7 +95,7 @@ module PgPipeline
     end
 
     def raise_close_error
-      error = @close_error || ShutdownError.new("queue closed")
+      error = @close_error || ShutdownError.new('queue closed')
       raise error.class, error.message
     end
   end

data/lib/pg_pipeline/client.rb

@@ -1,19 +1,20 @@
 # frozen_string_literal: true
 
-require_relative "errors"
-require_relative "pool"
-require_relative "request"
-require_relative "prepared_statement"
-require_relative "session_guard"
-require_relative "session"
-require_relative "transaction"
+require_relative 'errors'
+require_relative 'pool'
+require_relative 'request'
+require_relative 'prepared_statement'
+require_relative 'session_guard'
+require_relative 'session'
+require_relative 'transaction'
 
 module PgPipeline
   class Client
     attr_reader :guard
 
     def initialize(connection_args = nil, guard: :default, **pool_opts)
-      @owner_thread, @scheduler = nil, nil
+      @owner_thread = nil
+      @scheduler = nil
 
       @guard = SessionGuard.normalize_mode!(guard)
       @pool = Pool.new(connection_args, **pool_opts)
@@ -26,7 +27,11 @@ module PgPipeline
 
     def start = ClientOps.start(self)
     def query(sql, params = RequestOps::EMPTY_PARAMS) = ClientOps.query(self, sql, params)
-    def prepare(name, sql, param_types = nil) = ClientOps.prepare(self, name, sql, param_types)
+
+    def prepare(name, sql, param_types = nil, typed: false)
+      ClientOps.prepare(self, name, sql, param_types, typed: typed)
+    end
+
     def stats = ClientOps.stats(self)
 
     def session(&block)
@@ -42,9 +47,8 @@ module PgPipeline
 
     private
 
-    attr_reader :pool, :owner_thread, :scheduler
-    attr_accessor :started
-    attr_writer :owner_thread, :scheduler
+    attr_accessor :owner_thread, :scheduler, :started
+    attr_reader :pool
   end
 
   module ClientOps
@@ -54,16 +58,18 @@ module PgPipeline
       client = Client.new(connection_args, **opts).start
       yield client
     ensure
-      client.close if client
+      client&.close
     end
 
     def start(client)
-      raise Error, "client already started" if started?(client)
-      raise Error, "client start requires an active Fiber scheduler" unless Fiber.scheduler
+      raise Error, 'client already started' if started?(client)
+
+      scheduler = Fiber.scheduler
+      raise Error, 'client start requires an active Fiber scheduler' unless scheduler
 
       pool(client).start
       client.__send__(:owner_thread=, Thread.current)
-      client.__send__(:scheduler=, Fiber.scheduler)
+      client.__send__(:scheduler=, scheduler)
       client.__send__(:started=, true)
       client
     end
@@ -78,18 +84,22 @@ module PgPipeline
       end
     end
 
-    def prepare(client, name, sql, param_types)
+    def prepare(client, name, sql, param_types, typed: false)
       ensure_started!(client)
       sql = RequestOps.snapshot_sql(sql)
       SessionGuard.assert_multiplexable_normalized!(sql, mode: client.guard)
-      pool(client).__send__(:prepare_statement, client, name, sql, param_types)
+      pool(client).__send__(:prepare_statement, client, name, sql, param_types, typed: typed)
     end
 
     def query_prepared(client, statement, params)
       ensure_started!(client)
 
       wait_for_request do
-        submit_with_failover(client) { Request.prepared_query(statement, params: params) }
+        submit_with_failover(client) do
+          request = Request.prepared_query(statement, params: params)
+          pool(client).bind_type_map(request, statement) if statement.typed?
+          request
+        end
       end
     end
 
@@ -102,26 +112,38 @@ module PgPipeline
 
     def submit_with_failover(client)
       attempts = 0
-      limit = [pool(client).pipeline_size, 1].max
+      client_pool = pool(client)
+      limit = [client_pool.pipeline_size, 1].max
       last_error = nil
 
       while attempts < limit
         request = yield
-        begin
-          pool(client).__send__(:pipeline_driver).submit(request)
-          return request
-        rescue NotDispatchedError => e
-          last_error = e
-          attempts += 1
-        rescue ShutdownError => e
-          last_error = e
-          attempts += 1
-          break unless request.state == :new && !request.settled?
-        end
+        last_error = submit_attempt(client_pool, request)
+        return request unless last_error
+
+        attempts += 1
+        break if stop_retrying?(request, last_error)
       end
 
-      error = last_error || NotDispatchedError.new("no live pipeline connections; request was not dispatched")
-      raise(error.is_a?(NotDispatchedError) ? error : NotDispatchedError.new(error.message))
+      raise_submission_error(last_error)
+    end
+
+    def submit_attempt(client_pool, request)
+      client_pool.__send__(:pipeline_driver).submit(request)
+      nil
+    rescue NotDispatchedError, ShutdownError => e
+      e
+    end
+
+    def stop_retrying?(request, error)
+      error.is_a?(ShutdownError) && (request.state != :new || request.settled?)
+    end
+
+    def raise_submission_error(error)
+      error ||= NotDispatchedError.new('no live pipeline connections; request was not dispatched')
+      raise error if error.is_a?(NotDispatchedError)
+
+      raise NotDispatchedError, error.message
     end
 
     def session(client)
@@ -137,13 +159,13 @@ module PgPipeline
       end
     end
 
-    def transaction(client)
+    def transaction(client, &block)
       ensure_started!(client)
 
       pool(client).__send__(:with_pinned) do |conn|
         tx = Transaction.new(conn)
         begin
-          TransactionOps.run(tx) { |transaction| yield transaction }
+          TransactionOps.run(tx, &block)
         ensure
           SessionOps.close!(tx)
         end
@@ -159,10 +181,11 @@ module PgPipeline
       return unless started?(client)
 
       ensure_context!(client)
+      client_pool = pool(client)
       begin
-        pool(client).graceful_close
+        client_pool.graceful_close
       ensure
-        client.__send__(:started=, false) if pool(client).closing?
+        client.__send__(:started=, false) if client_pool.closing?
       end
     end
 
@@ -170,10 +193,11 @@ module PgPipeline
       return unless started?(client)
 
       ensure_context!(client)
+      client_pool = pool(client)
       begin
-        pool(client).abort!
+        client_pool.abort!
       ensure
-        client.__send__(:started=, false) if pool(client).closing?
+        client.__send__(:started=, false) if client_pool.closing?
       end
     end
 
@@ -182,7 +206,7 @@ module PgPipeline
     end
 
     def ensure_started!(client)
-      raise Error, "client not started; call #start or use Client.open" unless started?(client)
+      raise Error, 'client not started; call #start or use Client.open' unless started?(client)
 
       ensure_context!(client)
     end
@@ -191,7 +215,7 @@ module PgPipeline
       return if Thread.current.equal?(client.__send__(:owner_thread)) &&
                 Fiber.scheduler.equal?(client.__send__(:scheduler))
 
-      raise Error, "client is reactor-local and cannot be used from another thread/scheduler"
+      raise Error, 'client is reactor-local and cannot be used from another thread/scheduler'
     end
 
     def started?(client)