pg_pipeline 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6537ec11ece29a487aa35449c264d2bae69089022a28c473f71523e52fd2acd
-  data.tar.gz: 231b7285d0ddf23bb686836217ff35d1c89cc3872a5ac4ef20df28cea7e781bb
+  metadata.gz: 5ebb76f18598913316b77fdc0fd0ab4aa411fbd014cf1f3f10e427c1a5709967
+  data.tar.gz: cd51b3fc6b5f20f5896969e8eb3a4263d999f2544239606944194192f894e850
 SHA512:
-  metadata.gz: 31ef9eeacef9208296c2df0d29f5a83e0a2ee8a2278715bd4b67d261fb1561a5b0e11771856b5dfb27d34a28cb21034e7b6cda5408757f6e13672a3db65c8d3d
-  data.tar.gz: b686d8bd24fb976e8d9e6842b92db04988b1ae6f5981b297de57fc7d32b0add212d200f5b2906d5a7ea450b47bf46b9373a4404d5449ab24b702b189fb2a9131
+  metadata.gz: 6c1581a9ecc7f45b44342c49c529d12694c5d962808ef4ba7a0ec9d71aac5ae46852c99c242ec1b897c8c1b591d9ab66c55a24eacf0a4e6637de068624f36fc3
+  data.tar.gz: 3272e19424de3eed0f6c186b2bf14ac830ef226f9ce47207fd3c71fd38f622557a6542630c44934794cf9c650106a2e5a7e66ec475501220a685551799609111

data/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## [0.3.0] - 2026-08-07
+
+Scheduler-agnostic control plane: the gem no longer depends on the `async` gem
+at runtime. Any `Fiber::Scheduler` host works (Async::Scheduler, Itsi::Scheduler,
+or another `Fiber.set_scheduler` implementation).
+
+This unlocks hosts that were previously impossible. On our stand, Itsi with
+0.3.0 serves ~26% more req/s than the 0.2.5 Falcon baseline (29350 vs 23254,
+4 workers, `oha -z 60s -c 1000`) — a configuration 0.2.5 could not run at all,
+since it required an Async reactor. Falcon throughput itself is unchanged
+(23007 vs 23254, inside run-to-run spread): this is a portability change, and
+the speedup comes from being free to pick the host.
+
+### Changed
+
+- New `PgPipeline::Runtime` primitives (`Notification`, `Queue`, `Semaphore`,
+  `Task`, `spawn`, `with_timeout`, `Cancel`) built on `Fiber.scheduler`.
+- Driver/pool background work uses `Runtime.spawn` instead of `parent.async`.
+- Pinned-connection ownership keys on `Fiber.current` (not `Async::Task.current`).
+- Watcher shutdown closes queues + connection, then joins tasks with a timeout.
+- Timeouts go through `Timeout.timeout` (correct `timeout_after` arity), never a
+  direct one-arg `scheduler.timeout_after` call.
+- Closed `Runtime::Queue#enqueue` is a no-op; supervisor sleep errors are recorded
+  and `stats` exposes `supervisor_alive`.
+- `Client#start` / `Pool#start` / `ConnectionDriver#start` no longer take
+  `parent:` (no Async task-tree ownership; use `Runtime.spawn` on the active
+  scheduler). Call sites that passed `start(parent: task)` should use `#start`.
+- Runtime dependency: only `pg`. `async` is a development dependency for the
+  existing Async-based test harness.
+
+### Migration
+
+Hosts must install a Fiber scheduler before `Client#start`. Under Async:
+
+```ruby
+require "async"
+Sync { client.start; ... }
+```
+
+Under Itsi, the server installs `Itsi::Scheduler` for you — just `client.start`.
+
+Apps that previously relied on `pg_pipeline` pulling in `async` transitively
+should add `gem "async"` themselves if they still use Async.
+
+## [0.2.5] - 2026-08-03
+
+Control-plane cleanup on the multiplexed query path: fewer per-query allocations,
+a cheaper session-guard fast path, slightly tighter result drain, and driver
+fill metrics. Wire behaviour and the public API are unchanged.
+
+### Performance
+
+- `SessionGuard` skips comment/literal masking when the SQL has no quotes,
+  comments or dollar-quotes; skips the forbidden-pattern scan when the SQL has
+  neither `(` nor `into`; and uses a byte scan for multi-statement detection.
+- `Request.build` / `PreparedQueryRequest.build` avoid keyword `Class#new` hash
+  allocation on the hot path.
+- `RequestOps.snapshot_params` reuses a shared frozen empty array and skips
+  copying frozen immutable param arrays.
+- Default query params use that empty frozen array instead of allocating `[]`
+  per call (`Client`, `Session`, `PreparedStatement`).
+- `PoolOps.select_driver_into` writes the round-robin cursor into a pool-owned
+  slot instead of allocating a `[driver, cursor]` pair per selection.
+- `drain_results` matches hot statuses (`TUPLES_OK`, `PIPELINE_SYNC`) first and
+  accumulates `results_read` once per drain.
+
+### Observability
+
+- Driver stats add `fast_sync`, `units_per_readable`, `results_per_readable`,
+  `flush_calls`, `flush_incomplete`, `dispatches`, and `flush_calls_per_unit`.
+- One process-level warning on libpq older than 17 when Sync is coupled to flush
+  (`PG_PIPELINE_SILENCE_WARNINGS=1` to suppress).
+
+### Reliability
+
+- Round-robin cursor is normalised with `rr % size` when past the pool length.
+- Driver metric readers default to zero if ivars are unset.
+
+### Tests
+
+- Guard fast-path / masking / cache eviction coverage.
+- `Request.build` equivalence and prepared-query build coverage.
+- Randomised driver-selection vs reference algorithm.
+- Drain counter write-back when the loop raises.
+
 ## [0.2.4] - 2026-07-31
 
 Request-completion allocation patch. It replaces the general-purpose

data/DESIGN.md

@@ -240,6 +240,46 @@ that the request-specific one-shot waiter deliberately does not provide.
 > suite against the exact 2.42.0 floor so `Scheduler#block`/`#unblock` behavior is
 > not merely assumed from a broad pessimistic dependency range.
 
+## 10a. Guard evaluation shape
+
+`SessionGuard` validates the session-neutral SQL contract of §6 before a query is
+allowed onto the shared path, so its cost lands on the reactor thread and its
+stalls are visible in every other fiber's latency, not just the caller's.
+
+Evaluation is therefore staged so that the expensive stage runs only when it can
+change the answer:
+
+1. **Masking is skipped when it is provably an identity transform.** `code_only`
+   blanks string literals, quoted identifiers, comments and dollar-quoted bodies.
+   If none of `'`, `"`, `--`, `/*` or a `$tag$` delimiter appears in the SQL,
+   there is nothing to blank and the raw SQL is validated directly.
+2. **The forbidden-pattern scan is skipped when no pattern can match.** Every
+   pattern in `FORBIDDEN_PATTERNS` and `STRICT_FORBIDDEN` is anchored on either a
+   parenthesis or the word `into`, so SQL containing neither cannot match any of
+   them.
+3. **Verdicts are cached by SQL string**, and the cache evicts a single oldest
+   entry at its limit. Clearing the whole cache would turn one insertion into a
+   full recompute for every subsequent statement.
+
+Stage 1 and stage 2 are correctness-preserving only as long as their premises
+hold. Both are asserted in `spec/pg_pipeline/session_guard_fast_path_spec.rb`;
+**adding a pattern that is not anchored on `(` or `into` requires updating the
+prefilter in the same change.**
+
+Masking is deliberately monotone in the wrong direction to be reordered: blanking
+a comment can *create* a match (`nextval/* c */('s')` becomes `nextval      ('s')`),
+so the raw SQL can never be used as a negative filter for stage 2. Only the
+absence of maskable syntax justifies skipping stage 1.
+
+## 10b. Fill observability
+
+Pipelining pays off only when one reactor wakeup is amortised over several units.
+`ConnectionDriver#stats` therefore reports `units_per_readable` (and related
+counters) alongside the queue depths. A value near 1.0 means each query costs a
+full socket wait and a scheduler round trip, which bounds throughput
+independently of control-plane work; values well above 1.0 mean the pipeline is
+filling. Read this number before attributing throughput to Ruby-side cost.
+
 ## 11. Version policy
 
 | Component | Minimum | Reason |

data/README.md

@@ -24,13 +24,66 @@ At 10 ms RTT a naïve pool does ~100 queries/s per connection.
 A pipelined connection can do thousands — the wire stays full instead of sitting idle.
 
 `pg_pipeline` is the Ruby control plane that does exactly this: it multiplexes
-independent queries from many Async fibers onto a small pool of libpq connections,
+independent queries from many fibers onto a small pool of libpq connections,
 routes FIFO results back to the right fiber, and keeps transactional/session work
 on separate pinned connections. All wire protocol work stays in libpq; zero C code here.
 
 The single-owner connection model, FIFO result ownership, and lifecycle approach
 are directly inspired by tokio-postgres.
 
+## Any Fiber scheduler, not just Async
+
+Up to 0.2.x the control plane was built on the `async` gem: `Async::Task`,
+`Async::Queue`, `Async::Semaphore`, and a task tree rooted in Async's reactor.
+That made Falcon the only realistic host.
+
+0.3.0 removes that. The control plane is built on Ruby's `Fiber::Scheduler`
+interface — `Fiber.schedule` plus the scheduler's `block` / `unblock` — and on
+nothing else. The host installs whichever scheduler it likes; the gem never
+installs one and never calls a scheduler hook directly. `async` is now a
+development dependency only, and the sole runtime dependency is `pg`.
+
+```ruby
+# Falcon / any Async host — unchanged, still works
+Async do
+  client = PgPipeline::Client.open(ENV["DATABASE_URL"])
+  client.query("SELECT * FROM users WHERE id = $1", [id]).first
+end
+
+# Itsi, with its own scheduler — no Async anywhere
+# Itsi.rb:
+#   fiber_scheduler "Itsi::Scheduler"
+client = PgPipeline::Client.open(ENV["DATABASE_URL"])
+client.query("SELECT * FROM users WHERE id = $1", [id]).first
+```
+
+The call site does not change: `query` blocks the *fiber*, not the thread, so
+application code reads synchronously with no `await` and no coloured functions.
+The only hard requirement is that some scheduler is installed on the current
+thread — under a web server running requests in `Fiber.schedule` that is free,
+while a plain script or rake task must set one up itself.
+
+### What it buys
+
+On our benchmark stand (4 workers, `oha -z 60s -c 1000`, single-row lookup by
+primary key, local PostgreSQL 16):
+
+| gem | server | scheduler | req/s |
+|---|---|---|---:|
+| 0.2.5 | Falcon | Async | 23254 |
+| 0.3.0 | Falcon | Async | 23007 |
+| 0.3.0 | Itsi | Async | 29206 |
+| 0.3.0 | Itsi | Itsi::Scheduler | 29350 |
+
+Falcon throughput is unchanged — this was a portability change, not a
+Falcon optimisation. The gain comes from being *able* to move: an Itsi host is
+roughly **26% faster than the 0.2.5 Falcon baseline**, and that configuration
+simply could not run before, because 0.2.5 required an Async reactor.
+
+Numbers from one stand on one machine; treat them as a direction, not a
+guarantee. Your own ratio depends on payload size, RTT, and how much of the
+request is spent outside the database.
+
 ## Installation
 
 ```ruby
@@ -40,6 +93,14 @@ gem "pg_pipeline"
 
 Requires Ruby ≥ 3.3, `async ~> 2.42`, `pg ≥ 1.5`, and **libpq ≥ 14** at runtime.
 
+**libpq ≥ 17 is recommended for maximum local throughput.** Below 17 there is no
+`PQsendPipelineSync`, so `PQpipelineSync` couples Sync with a flush and the driver
+cannot batch writes across a dispatch burst. Correctness is identical and RTT
+amortisation — the main reason to pipeline — still works on libpq 14; only local
+throughput is capped. The driver detects this at connect time and warns once per
+process; set `PG_PIPELINE_SILENCE_WARNINGS=1` to suppress it, and check
+`db.stats[:pipeline][:drivers].first[:fast_sync]` to see which path is active.
+
 ## Usage
 
 ### Multiplexed queries
@@ -155,6 +216,49 @@ db.stats
 
 `load` (pending + in-flight + submitting + dispatching) per driver is the routing/head-of-line signal.
 
+Each driver also reports how well the pipeline is filling:
+
+```ruby
+db.stats[:pipeline][:drivers].first
+# => { ..., fast_sync: true,
+#      units_per_readable: 7.9, results_per_readable: 22.2,
+#      flush_calls_per_unit: 0.17, flush_incomplete: 0 }
+```
+
+`units_per_readable` is the number to watch. Around `1.0` means every query pays a
+full socket wait plus scheduler round trip and the pipeline is not filling — that is
+the expected shape for a single fiber issuing one query at a time, and no amount of
+Ruby-side optimisation will change it. Values well above `1.0` mean one reactor
+wakeup is amortised over many queries, which is the regime pipelining is for. Check
+this before attributing a throughput number to control-plane cost.
+
+The numbers above are from a saturated HTTP benchmark (4 workers, 4 connections
+each, ~20k requests/second against a local server): roughly eight queries per
+reactor wakeup and one flush per six queries. `results_per_readable` runs at
+three times `units_per_readable` because a completed unit yields three protocol
+results -- the data, the query boundary and the Sync.
+
+## Head-of-line blocking
+
+Results on a pipelined connection arrive in FIFO order, and PostgreSQL offers no
+safe way to cancel one request out of a multiplexed pipeline (see `DESIGN.md` §7).
+Two consequences worth designing around:
+
+- **A slow query delays everything behind it on the same connection.** With the
+  default `max_in_flight: 64`, one multi-second query can hold up to 63 unrelated
+  queries on that driver. Driver selection balances by queue depth, not by expected
+  cost, so a slow query counts the same as a fast one.
+- **A timeout is not a cancellation.** Wrapping `db.query` in `with_timeout` returns
+  control to your fiber, but the unit stays in the pipeline until the server answers
+  it, and the requests behind it still wait.
+
+If your workload mixes fast and slow queries, prefer one of:
+
+- lower `max_in_flight` so a stall cannot capture a deep queue;
+- a second `Client` with its own connections for the slow queries;
+- `Client#session` for anything long-running, which uses an exclusive pinned
+  connection and cannot block multiplexed traffic.
+
 ## Failure model
 
 | Error | Meaning | Retry safe? |

data/lib/pg_pipeline/bounded_queue.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require "async/notification"
-
 require_relative "errors"
+require_relative "runtime"
 
 module PgPipeline
   class BoundedQueue
@@ -12,15 +11,14 @@ module PgPipeline
     rescue ArgumentError, TypeError
       raise ArgumentError, "limit must be an integer >= 1"
     else
-      @items = []
-      @consumers = []
-      @producers = []
+      @items, @consumers, @producers = [], [], []
+
       @closed = false
       @close_error = nil
     end
 
     def enqueue(item)
-      loop do
+      while true
         raise_close_error if @closed
 
         if @items.size < @limit
@@ -34,7 +32,7 @@ module PgPipeline
     end
 
     def dequeue
-      loop do
+      while true
         unless @items.empty?
           item = @items.shift
           wake_one(@producers)
@@ -72,13 +70,13 @@ module PgPipeline
     private
 
     def wait_on(list)
-      notification = Async::Notification.new
+      notification = Runtime::Notification.new
       list << notification
       completed = false
-      begin
-        notification.wait
-        completed = true
-      ensure
+      notification.wait
+      completed = true
+    ensure
+      if notification
         still_queued = list.delete(notification)
         wake_one(list) if !completed && still_queued.nil? && !@closed
       end

data/lib/pg_pipeline/client.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "async"
-
 require_relative "errors"
 require_relative "pool"
 require_relative "request"
@@ -15,19 +13,19 @@ module PgPipeline
     attr_reader :guard
 
     def initialize(connection_args = nil, guard: :default, **pool_opts)
+      @owner_thread, @scheduler = nil, nil
+
       @guard = SessionGuard.normalize_mode!(guard)
       @pool = Pool.new(connection_args, **pool_opts)
       @started = false
-      @owner_thread = nil
-      @scheduler = nil
     end
 
     def self.open(connection_args = nil, **opts, &block)
       ClientOps.open(connection_args, opts, &block)
     end
 
-    def start(parent: Async::Task.current) = ClientOps.start(self, parent)
-    def query(sql, params = []) = ClientOps.query(self, sql, params)
+    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 stats = ClientOps.stats(self)
 
@@ -54,17 +52,16 @@ module PgPipeline
 
     def open(connection_args, opts)
       client = Client.new(connection_args, **opts).start
-      begin
-        yield client
-      ensure
-        client.close
-      end
+      yield client
+    ensure
+      client.close if client
     end
 
-    def start(client, parent)
+    def start(client)
       raise Error, "client already started" if started?(client)
+      raise Error, "client start requires an active Fiber scheduler" unless Fiber.scheduler
 
-      pool(client).start(parent: parent)
+      pool(client).start
       client.__send__(:owner_thread=, Thread.current)
       client.__send__(:scheduler=, Fiber.scheduler)
       client.__send__(:started=, true)
@@ -77,7 +74,7 @@ module PgPipeline
       SessionGuard.assert_multiplexable_normalized!(sql, mode: client.guard)
 
       wait_for_request do
-        submit_with_failover(client) { Request.new(sql: sql, params: params) }
+        submit_with_failover(client) { Request.build(sql, params) }
       end
     end
 
@@ -98,15 +95,11 @@ module PgPipeline
 
     def wait_for_request
       request = yield
-      begin
-        request.wait
-      ensure
-        request.cancel! unless request.settled?
-      end
+      request.wait
+    ensure
+      request.cancel! if request && !request.settled?
     end
 
-    # NotDispatchedError is safe to retry on a fresh Request by contract.
-    # ShutdownError is retried only while the current Request is still pre-dispatch.
     def submit_with_failover(client)
       attempts = 0
       limit = [pool(client).pipeline_size, 1].max