pipeloader 0.0.1 → 0.0.3

data/lib/pipeloader/field_exact.rb

@@ -1,10 +1,14 @@
 module Pipeloader
-  # Opt-in, off by default. Set true before your schema's types are defined to
-  # turn on projection everywhere; or opt in per type with `pipeloader_field_exact!`.
+  # Both opt-in, off by default; set before your schema's types are defined.
+  # `field_exact` turns on column projection (+ fusion) everywhere (or per type via
+  # `pipeloader_field_exact!`). `auto_fuse` turns on whole-row association fusion
+  # with no projection — plain `object.author` / `object.comments` collapse to one
+  # `WHERE key = ANY($1)` per level, byte-identical to the un-fused result.
   class << self
-    attr_accessor :field_exact
+    attr_accessor :field_exact, :auto_fuse
   end
   self.field_exact = false
+  self.auto_fuse = false
 
   # Per-type opt-in, mixed into every GraphQL::Schema::Object.
   module TypeOptIn
@@ -26,8 +30,12 @@ module Pipeloader
 
     def initialize(*args, selects: nil, owner: nil, extensions: [], **kwargs, &block)
       @pipeloader_selects = selects && Array(selects).map(&:to_s)
+      # At most one extension: field-exact (projects + fuses) wins over auto-fuse
+      # (whole-row fuses only). Both bail to plain resolution for non-associations.
       if Pipeloader.field_exact || (owner.respond_to?(:pipeloader_field_exact?) && owner.pipeloader_field_exact?)
         extensions = extensions + [ProjectionExtension]
+      elsif Pipeloader.auto_fuse
+        extensions = extensions + [FusionExtension]
       end
       super(*args, owner: owner, extensions: extensions, **kwargs, &block)
     end
@@ -43,18 +51,45 @@ module Pipeloader
       lookahead = arguments[:lookahead]
       inner = arguments.key?(:lookahead) ? arguments.reject { |k, _| k == :lookahead } : arguments
 
-      # A belongs_to is loaded whole-row by `object.assoc`, so resolve it via a
-      # projected query instead (still pipelined). Skipped if the type defines a
-      # custom resolver, or the selection is opaque (then fall through to default).
+      # belongs_to and has_one are singular associations AR loads whole-row via
+      # `object.assoc`; resolve them with a projected (and, when safe, fused) query
+      # instead. Skipped if the type defines a custom resolver, or the selection is
+      # opaque (then fall through to default).
       record = object.respond_to?(:object) ? object.object : object
       if lookahead && record.is_a?(ActiveRecord::Base) &&
          !field.owner.instance_methods(false).include?(field.resolver_method) &&
-         (assoc = record.class.reflect_on_association(field.method_str.to_sym))&.belongs_to?
-        fk = record.public_send(assoc.foreign_key)
-        return nil if fk.nil?
+         (assoc = record.class.reflect_on_association(field.method_str.to_sym))
+        if assoc.belongs_to?
+          fk = record.public_send(assoc.foreign_key)
+          return nil if fk.nil?
 
-        cols = Pipeloader.project_columns(assoc.klass, lookahead)
-        return assoc.klass.where(assoc.klass.primary_key => fk).select(*cols).first if cols
+          cols = Pipeloader.project_columns(assoc.klass, lookahead)
+          if cols
+            # Mechanical batch: gather the level's foreign keys and resolve them with
+            # one `WHERE pk = ANY($1)` instead of a query per parent, when demux is
+            # provably unambiguous (see fusable_belongs_to?). The fused query is itself
+            # pipelined, so round-trips stay = tree depth.
+            if Pipeloader.fusable_belongs_to?(assoc)
+              return Pipeloader.fuse(context.dataloader, assoc.klass, :by_pk, assoc.klass.primary_key, cols.sort, fk)
+            end
+            return assoc.klass.where(assoc.klass.primary_key => fk).select(*cols).first
+          end
+        elsif assoc.macro == :has_one && assoc.scope.nil? && assoc.through_reflection.nil?
+          parent_key = record.public_send(assoc.active_record_primary_key)
+          return nil if parent_key.nil?
+
+          cols = Pipeloader.project_columns(assoc.klass, lookahead)
+          if cols
+            cols = (cols + [assoc.foreign_key]).uniq
+            # has_one is the has_many query with a single-row demux. Fusing it is only
+            # unambiguous when a unique index on the FK enforces 1:1 — otherwise the
+            # ANY-scan's "first" could differ from the per-parent LIMIT 1.
+            if Pipeloader.fusable_has_one?(assoc)
+              return Pipeloader.fuse(context.dataloader, assoc.klass, :by_fk_one, assoc.foreign_key, cols.sort, parent_key)
+            end
+            return assoc.klass.where(assoc.foreign_key => parent_key).select(*cols).first
+          end
+        end
       end
 
       value = yield(object, inner)
@@ -63,14 +98,200 @@ module Pipeloader
       cols = Pipeloader.project_columns(value.klass, lookahead)
       return value unless cols # opaque field selected -> fetch whole rows
 
-      # Keep a has_many's foreign key so AR can still group / wire the inverse.
-      if value.respond_to?(:proxy_association) && (proxy = value.proxy_association)
-        cols += Array(proxy.reflection.foreign_key)
+      proxy = value.respond_to?(:proxy_association) ? value.proxy_association : nil
+      if proxy && Pipeloader.fusable_has_many?(proxy.reflection, value)
+        # Mechanical batch: gather the level's parent keys and load all children
+        # with one `WHERE fk IN (...)`, grouped back by foreign key. Safe only for a
+        # plain has_many (no scope/limit), so each child row belongs to one parent.
+        refl = proxy.reflection
+        cols = (cols + [refl.foreign_key]).uniq
+        parent_key = proxy.owner.public_send(refl.active_record_primary_key)
+        return Pipeloader.fuse(context.dataloader, refl.klass, :by_fk_many, refl.foreign_key, cols.sort, parent_key)
       end
+
+      # Keep a has_many's foreign key so AR can still group / wire the inverse.
+      cols += Array(proxy.reflection.foreign_key) if proxy
       value.select(*cols.uniq)
     end
   end
 
+  # The auto-fuse sibling of ProjectionExtension: fuses a plain association field
+  # into one `WHERE key = ANY($1)` per level (reusing the same sources and safety
+  # gates) but selects the WHOLE row and never narrows. Anything that isn't a
+  # fusable association — scalars, custom resolvers, non-AR objects, polymorphic /
+  # scoped / non-unique associations, SQLite — just yields and loads normally
+  # through the transparent pipelined path. Result is byte-identical, just batched.
+  class FusionExtension < GraphQL::Schema::FieldExtension
+    def resolve(object:, arguments:, context:, **)
+      record = object.respond_to?(:object) ? object.object : object
+      if record.is_a?(ActiveRecord::Base) &&
+         !field.owner.instance_methods(false).include?(field.resolver_method) &&
+         (assoc = record.class.reflect_on_association(field.method_str.to_sym))
+        if assoc.belongs_to? && Pipeloader.fusable_belongs_to?(assoc)
+          fk = record.public_send(assoc.foreign_key)
+          return nil if fk.nil?
+
+          return Pipeloader.fuse(context.dataloader, assoc.klass, :by_pk, assoc.klass.primary_key, assoc.klass.column_names.sort, fk)
+        elsif assoc.macro == :has_one && Pipeloader.fusable_has_one?(assoc)
+          parent_key = record.public_send(assoc.active_record_primary_key)
+          return nil if parent_key.nil?
+
+          return Pipeloader.fuse(context.dataloader, assoc.klass, :by_fk_one, assoc.foreign_key, assoc.klass.column_names.sort, parent_key)
+        end
+      end
+
+      value = yield(object, arguments)
+      return value unless value.is_a?(ActiveRecord::Relation)
+
+      proxy = value.respond_to?(:proxy_association) ? value.proxy_association : nil
+      if proxy && Pipeloader.fusable_has_many?(proxy.reflection, value)
+        refl = proxy.reflection
+        parent_key = proxy.owner.public_send(refl.active_record_primary_key)
+        return Pipeloader.fuse(context.dataloader, refl.klass, :by_fk_many, refl.foreign_key, refl.klass.column_names.sort, parent_key)
+      end
+
+      value # bare relation/record -> loads whole-row through the transparent path
+    end
+  end
+
+  ARRAY_ENCODER = PG::TextEncoder::Array.new
+
+  # Build `<key> = ANY($1)` with a single array bind, so a fused query is one stable
+  # prepared statement regardless of batch size (an IN-list is a distinct statement
+  # per length and re-plans with a custom plan each execution; ANY(array) plans once
+  # as a generic array scan). PostgreSQL-specific, which is fine: fusion is the
+  # gathering side of pipelining, and only PostgreSQL pipelines (see fusable_* —
+  # they gate it). The fused query flows through the AR patch, so it's pipelined.
+  def self.any_relation(model, key, values, columns)
+    qualified = "#{model.quoted_table_name}.#{model.connection.quote_column_name(key)}"
+    model.where("#{qualified} = ANY(?)", ARRAY_ENCODER.encode(values)).select(*columns)
+  end
+
+  # The [sql, params] an `any_relation` would send through the AR patch — pulled out
+  # so FusionSource can enqueue it on Pipeloader::Source directly (via `request`,
+  # without forcing) instead of letting `.to_a` force one query at a time.
+  def self.sql_and_params(relation)
+    conn = relation.klass.connection
+    sql, binds = conn.send(:to_sql_and_binds, relation.arel)
+    [sql, binds.map { |b| b.respond_to?(:value_for_database) ? b.value_for_database : b }]
+  end
+
+  # Issue one fused association lookup. `kind` is :by_pk (belongs_to, demux by primary
+  # key, single), :by_fk_one (has_one, demux by FK, first) or :by_fk_many (has_many,
+  # demux by FK, array). All fused lookups on a connection share ONE FusionSource.
+  def self.fuse(dataloader, model, kind, key, columns, value)
+    dataloader.with(FusionSource, model.connection)
+              .load([kind, model, key, columns, value].freeze)
+  end
+
+  # One source for EVERY safe association lookup parked at a fiber tick — across all
+  # models and macros. graphql-ruby runs sibling sources sequentially in one fiber, so
+  # a separate source per association would force its own `WHERE key = ANY($1)` query
+  # before the next ran, adding a round trip per association on a level. Funnelling them
+  # through a single source lets `fetch` enqueue every shape's query on Pipeloader::Source
+  # WITHOUT forcing (`request`), then force them together — so a whole level's fused
+  # lookups collapse into one pipeline burst and round trips stay = tree depth.
+  class FusionSource < GraphQL::Dataloader::Source
+    def initialize(conn)
+      @conn = conn
+    end
+
+    # descriptors: [kind, model, key, columns, value], deduped by Dataloader (so two
+    # parents sharing a belongs_to target hit the DB once). Returns one demuxed value
+    # per descriptor, in order.
+    def fetch(descriptors)
+      src = @dataloader.with(Pipeloader::Source, @conn)
+
+      # One `WHERE key = ANY($1)` per distinct query shape, enqueued but not forced.
+      pending = descriptors.group_by { |d| d[0, 4] }.map do |(kind, model, key, columns), ds|
+        values = ds.map { |d| d[4] }.uniq
+        rel = Pipeloader.any_relation(model, key, values, columns)
+        # Order FK lookups by child PK so an unordered association comes back
+        # deterministically (group_by is stable, so each parent keeps that order).
+        rel = rel.order(model.arel_table[model.primary_key].asc) unless kind == :by_pk
+        [kind, model, key, columns, src.request(Pipeloader.sql_and_params(rel))]
+      end
+
+      # Forcing the first request runs Pipeloader::Source once for ALL enqueued shapes
+      # (one burst); the rest read straight from its cache. Then demux each shape.
+      demux = pending.to_h do |kind, model, key, columns, request|
+        rows = request.load.map { |attrs| model.instantiate(attrs) }
+        bucket = kind == :by_pk ? rows.index_by { |r| r.public_send(model.primary_key) } : rows.group_by { |r| r.public_send(key) }
+        [[kind, model, key, columns], bucket]
+      end
+
+      descriptors.map do |kind, model, key, columns, value|
+        bucket = demux[[kind, model, key, columns]]
+        case kind
+        when :by_pk      then bucket[value]          # nil for a dangling/absent target
+        when :by_fk_one  then bucket[value]&.first    # has_one: first/nil
+        else                  bucket[value] || []      # has_many: array
+        end
+      end
+    end
+  end
+
+  # Only fuse when each returned row maps back to exactly one parent with zero
+  # ambiguity: a non-polymorphic, unscoped belongs_to keyed by a single-column
+  # primary key (unique), on PostgreSQL (the only adapter that pipelines/fuses).
+  # Anything else keeps the per-parent projected query.
+  def self.fusable_belongs_to?(assoc)
+    assoc.belongs_to? && !assoc.polymorphic? && assoc.scope.nil? &&
+      assoc.klass.primary_key.is_a?(String) &&
+      assoc.klass.connection.adapter_name == "PostgreSQL"
+  rescue StandardError
+    false
+  end
+
+  # has_one fuses like has_many but with a single-row demux, so it's exact only when
+  # the FK is genuinely 1:1 — proven by a unique index on the FK. Without it, "first"
+  # is ambiguous and we keep the per-parent query.
+  def self.fusable_has_one?(assoc)
+    assoc.macro == :has_one && assoc.through_reflection.nil? && assoc.scope.nil? &&
+      assoc.foreign_key.is_a?(String) && assoc.active_record_primary_key.is_a?(String) &&
+      assoc.klass.connection.adapter_name == "PostgreSQL" &&
+      unique_fk_index?(assoc)
+  rescue StandardError
+    false
+  end
+
+  # A unique index on exactly the FK column proves at most one child per parent.
+  # Memoized per reflection.
+  def self.unique_fk_index?(assoc)
+    @unique_fk_indexes ||= {}
+    return @unique_fk_indexes[assoc.object_id] if @unique_fk_indexes.key?(assoc.object_id)
+
+    fk = assoc.foreign_key
+    @unique_fk_indexes[assoc.object_id] =
+      assoc.klass.connection.indexes(assoc.klass.table_name).any? { |ix| ix.unique && Array(ix.columns) == [fk] }
+  end
+
+  # Fuse only a plain has_many: no scope, no `through`, and no per-parent
+  # limit/offset (those need a lateral join, not a flat IN — order is preserved by
+  # group_by, so it's fine). Single-column keys only. Then group_by(fk) is exact.
+  def self.fusable_has_many?(reflection, relation)
+    reflection.macro == :has_many &&
+      reflection.through_reflection.nil? &&
+      reflection.scope.nil? &&
+      reflection.foreign_key.is_a?(String) &&
+      reflection.active_record_primary_key.is_a?(String) &&
+      reflection.klass.connection.adapter_name == "PostgreSQL" &&
+      bare_association?(reflection, relation)
+  rescue StandardError
+    false
+  end
+
+  # The relation must be the *bare* association — nothing chained onto it. The fused
+  # query is rebuilt from the reflection, so any chained order / where / limit would
+  # be silently dropped; comparing the relation's SQL to the untouched association
+  # scope catches all of them at once (order, where, limit, joins, group, ...).
+  # Ordered or filtered collections fall back to the per-parent query, which keeps them.
+  def self.bare_association?(reflection, relation)
+    owner_key = relation.where_values_hash[reflection.foreign_key]
+    !owner_key.nil? &&
+      relation.to_sql == reflection.klass.where(reflection.foreign_key => owner_key).to_sql
+  end
+
   # Returns the exact column list for a model + selection, or nil meaning
   # "can't prove it's safe — fetch whole rows."
   def self.project_columns(model, lookahead)

data/lib/pipeloader/pipeliner.rb

@@ -5,45 +5,133 @@ module Pipeloader
   module Pipeliner
     module_function
 
-    # queries: array of [sql, params]. Returns array of [columns, rows] (raw
-    # strings), in the same order, having sent them all in a single round trip.
+    # queries: array of [sql, params]. Returns array of [columns, rows, oids]
+    # (raw string values + per-column [oid, fmod] so the Source can type them),
+    # in the same order, having sent them all in a single round trip.
+    #
+    # Prepared statements are cached for the lifetime of the REQUEST (the cache and
+    # name space are set up by Pipeloader::Trace per multiplex), so a shape is
+    # planned once per request and reused across every burst — not re-planned each
+    # burst. They're thrown out when the next request begins: each request's first
+    # burst DEALLOCATEs the previous request's statements, piggybacked into the same
+    # pipeline so cleanup costs no extra round trip. Nothing outlives a request, so
+    # no plan goes stale across a reconnect or a migration.
+    #
+    # If any query errors, the pipeline is drained to its sync point, the connection
+    # is restored to a usable state, and the first error is raised — never swallowed.
     def pipeline_batch(pg, queries)
-      prepared = pg.instance_variable_get(:@pipeloader_prepared)
-      unless prepared
-        prepared = {}
-        pg.instance_variable_set(:@pipeloader_prepared, prepared)
-      end
+      cache = prepared_cache(pg)
+      seq = pg.instance_variable_get(:@pipeloader_seq) || 0
+      garbage = take_garbage(pg) # previous request's statements, to DEALLOCATE now
 
-      # Prepare any unseen SQL before entering pipeline mode (Parse can't be
-      # issued synchronously mid-pipeline). GraphQL has a bounded set of query
-      # shapes, so this amortizes to ~one parse per shape for the connection's
-      # life; thereafter every execution reuses the named statement.
+      # Name + pipelined Parse for each shape not yet prepared this request.
+      to_prepare = []
       queries.each do |sql, _params|
-        prepared[sql] ||= begin
-          name = "pipeloader_#{prepared.size}"
-          pg.prepare(name, sql)
-          name
+        next if cache.key?(sql)
+        name = "pipeloader_#{seq}_#{cache.size}"
+        cache[sql] = name
+        to_prepare << [name, sql]
+      end
+
+      error = nil
+      results = []
+      begin
+        pg.enter_pipeline_mode
+
+        # Block 1 — clean up the previous request, in its own sync so a stale name
+        # (after a reconnect) can't abort this burst's real queries. Same round trip.
+        unless garbage.empty?
+          garbage.each { |name| pg.send_query_params("DEALLOCATE #{name}", []) }
+          pg.pipeline_sync
         end
+
+        # Block 2 — prepare new shapes, run every query.
+        to_prepare.each { |name, sql| pg.send_prepare(name, sql) }
+        queries.each { |sql, params| pg.send_query_prepared(cache[sql], params) }
+        pg.pipeline_sync
+
+        drain_block(pg, nil, false) unless garbage.empty? # cleanup results — ignore failures
+        error = drain_block(pg, results, true)            # this burst's query results
+      ensure
+        finish_pipeline(pg)
       end
 
-      pg.enter_pipeline_mode
-      queries.each { |sql, params| pg.send_query_prepared(prepared[sql], params) }
-      pg.pipeline_sync
+      raise error if error
+      results
+    end
 
-      results = []
+    # Reads one pipeline sync block. Collects PGRES_TUPLES_OK into `results` (when
+    # given) and, when capturing, records the first query error via result.check.
+    def drain_block(pg, results, capture_error)
+      error = nil
       loop do
         result = pg.get_result
         break if result.nil?
-        break if result.result_status == PG::PGRES_PIPELINE_SYNC
 
-        # Raw strings, so ActiveRecord casts via its own column types (and so we
-        # never disturb the connection's type map that AR relies on).
-        result.type_map = PG::TypeMapAllStrings.new
-        results << [result.fields, result.values]
-        pg.get_result # per-query nil delimiter
+        status = result.result_status
+        break if status == PG::PGRES_PIPELINE_SYNC
+
+        if status == PG::PGRES_TUPLES_OK && results
+          # Read values as strings (so we never disturb the connection's type map
+          # that AR relies on), and capture each column's result OID + modifier so
+          # the Source can resolve the real type via the adapter's get_oid_type —
+          # including computed/aliased columns the model has no column type for.
+          # ftype/fmod are result metadata, unaffected by the all-strings map.
+          result.type_map = PG::TypeMapAllStrings.new
+          oids = Array.new(result.nfields) { |i| [result.ftype(i), result.fmod(i)] }
+          results << [result.fields, result.values, oids]
+        elsif status != PG::PGRES_COMMAND_OK && capture_error
+          begin
+            result.check
+          rescue PG::Error => e
+            error ||= e
+          end
+        end
+        pg.get_result # consume this result's nil delimiter
       end
+      error
+    end
+
+    # The per-request name cache, lazily created (Trace normally seeds it).
+    def prepared_cache(pg)
+      cache = pg.instance_variable_get(:@pipeloader_prepared)
+      return cache if cache
+
+      cache = {}
+      pg.instance_variable_set(:@pipeloader_prepared, cache)
+      cache
+    end
+
+    # Names left by previous requests, to DEALLOCATE on the next burst (cleared).
+    def take_garbage(pg)
+      garbage = pg.instance_variable_get(:@pipeloader_garbage)
+      return [] unless garbage && !garbage.empty?
+
+      pg.instance_variable_set(:@pipeloader_garbage, [])
+      garbage
+    end
+
+    # Leave the connection usable no matter how the batch ended. If the pipeline
+    # can't be drained cleanly (e.g. the connection dropped mid-burst), reset it so
+    # the pool gets a healthy connection.
+    def finish_pipeline(pg)
+      return if pg.pipeline_status == PG::PQ_PIPELINE_OFF
+
+      loop { break if pg.get_result.nil? }
       pg.exit_pipeline_mode
-      results
+    rescue PG::Error
+      reset_connection(pg)
+    end
+
+    def reset_connection(pg)
+      pg.reset
+    rescue PG::Error
+      nil
+    ensure
+      # The reset session has no prepared statements: drop the request's name cache
+      # so later bursts re-prepare, and the pending garbage that's now gone with it.
+      pg.instance_variable_get(:@pipeloader_prepared)&.clear
+      pg.instance_variable_set(:@pipeloader_garbage, [])
     end
   end
 end

data/lib/pipeloader/source.rb

@@ -3,8 +3,12 @@ module Pipeloader
   # and runs them as one pipelined burst, returning an ActiveRecord::Result per
   # query (so AR builds models normally).
   class Source < GraphQL::Dataloader::Source
-    def initialize(pg)
-      @pg = pg
+    # conn: the AR connection threaded in from the call site (the QueryCache
+    # patch's own connection, or the model's in FusionSource). @pg drives the
+    # pipeline; @conn supplies the OID -> type lookup for building typed results.
+    def initialize(conn)
+      @conn = conn
+      @pg = conn.raw_connection
     end
 
     # keys: array of [sql, params], deduplicated by Dataloader. Must return one
@@ -13,7 +17,27 @@ module Pipeloader
       batch = Pipeliner.pipeline_batch(@pg, keys)
       Pipeloader.round_trips += 1
       Pipeloader.queries += keys.size
-      batch.map { |columns, rows| ActiveRecord::Result.new(columns, rows) }
+      batch.map { |columns, rows, oids| to_ar_result(columns, rows, oids) }
+    end
+
+    private
+
+    # Build a typed ActiveRecord::Result from the raw-string rows. The model casts
+    # its own table columns, but a computed/aliased column (`COUNT(*) AS n`,
+    # `view_count > 1 AS hot`) has no model type, so without help it would stay the
+    # raw Postgres string — and "f" is truthy in Ruby. Resolve each column's type
+    # from its result OID via the adapter's own get_oid_type (exactly what AR does
+    # for a normal query), keyed by both name and index so AR's Result finds it on
+    # every supported version (7.x looks up column_types by name, 8.x by index).
+    def to_ar_result(columns, rows, oids)
+      column_types = {}
+      columns.each_with_index do |name, i|
+        oid, fmod = oids[i]
+        type = @conn.send(:get_oid_type, oid, fmod, name)
+        column_types[name] = type
+        column_types[i] = type
+      end
+      ActiveRecord::Result.new(columns, rows, column_types)
     end
   end
 end

data/lib/pipeloader/version.rb

@@ -1,3 +1,3 @@
 module Pipeloader
-  VERSION = "0.0.1"
+  VERSION = "0.0.3"
 end

data/lib/pipeloader.rb

@@ -7,6 +7,7 @@ require_relative "pipeloader/pipeliner"
 require_relative "pipeloader/source"
 require_relative "pipeloader/ar_patch"
 require_relative "pipeloader/field_exact"
+require_relative "pipeloader/batch"
 
 # Pipeloader makes a graphql-ruby query resolve its ActiveRecord SELECTs through
 # a libpq pipeline: one round trip per tree level, transparently. Resolvers stay
@@ -53,6 +54,30 @@ module Pipeloader
     end
   end
 
+  # Prepared statements are scoped to one request. Each multiplex gets a fresh,
+  # uniquely-prefixed name space; pipeline_batch fills it in and reuses it across
+  # bursts, so a shape is planned once per request rather than once per burst.
+  def self.begin_request!(pg)
+    pg.instance_variable_set(:@pipeloader_seq, (pg.instance_variable_get(:@pipeloader_seq) || 0) + 1)
+    pg.instance_variable_set(:@pipeloader_prepared, {})
+  end
+
+  # Hand the request's statements to the next one to DEALLOCATE (piggybacked onto
+  # its first burst — no extra round trip here). A plan therefore never outlives
+  # the request that made it.
+  def self.end_request!(pg)
+    cache = pg.instance_variable_get(:@pipeloader_prepared)
+    pg.remove_instance_variable(:@pipeloader_prepared) if pg.instance_variable_defined?(:@pipeloader_prepared)
+    return if cache.nil? || cache.empty?
+
+    garbage = pg.instance_variable_get(:@pipeloader_garbage)
+    unless garbage
+      garbage = []
+      pg.instance_variable_set(:@pipeloader_garbage, garbage)
+    end
+    garbage.concat(cache.values)
+  end
+
   # Stash the active dataloader on the connection for the whole response phase,
   # and clear it at the end. This is done at *multiplex* scope, not per-query,
   # because under Dataloader resolution is deferred to the multiplex's fiber run
@@ -61,12 +86,18 @@ module Pipeloader
     def execute_multiplex(multiplex:)
       Pipeloader.reset_stats!
       conn = ActiveRecord::Base.connection
+      pg = nil
       # Raises on an unsupported adapter; on SQLite, leaves the stash unset so
       # select_all never pipelines (column projection still applies).
-      conn.pipeloader_dataloader = multiplex.dataloader if Pipeloader.pipelining_supported?(conn)
+      if Pipeloader.pipelining_supported?(conn)
+        conn.pipeloader_dataloader = multiplex.dataloader
+        pg = conn.raw_connection
+        Pipeloader.begin_request!(pg)
+      end
       super
     ensure
       conn.pipeloader_dataloader = nil if conn
+      Pipeloader.end_request!(pg) if pg
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pipeloader
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Joshua Hull
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: graphql
   requirement: !ruby/object:Gem::Requirement
@@ -79,19 +93,47 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '13'
-description: During GraphQL response building, Pipeloader routes ActiveRecord SELECTs
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: 'During GraphQL response building, Pipeloader routes ActiveRecord SELECTs
   through a libpq pipeline so a query tree resolves in roughly one round trip per
   level — with plain resolvers and plain models, no Futures, no dataloader.load, no
-  resolver changes.
+  resolver changes. Also ships Pipeloader::Batch: declarative batch-loaded associations
+  and aggregates that eliminate N+1 in plain ActiveRecord traversal via AR''s own
+  Preloader.'
 email:
 - josh@fireflop.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- DATALOADERS.md
+- LICENSE
 - README.md
 - lib/pipeloader.rb
 - lib/pipeloader/ar_patch.rb
+- lib/pipeloader/batch.rb
+- lib/pipeloader/batch/batch_loader.rb
+- lib/pipeloader/batch/batch_proxy.rb
+- lib/pipeloader/batch/context.rb
+- lib/pipeloader/batch/fetcher.rb
+- lib/pipeloader/batch/fetcher_state.rb
+- lib/pipeloader/batch/load_grouping.rb
+- lib/pipeloader/batch/load_interceptor.rb
+- lib/pipeloader/batch/model.rb
+- lib/pipeloader/batch/relationship.rb
 - lib/pipeloader/field_exact.rb
 - lib/pipeloader/pipeliner.rb
 - lib/pipeloader/source.rb
@@ -116,5 +158,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: Transparent libpq pipelining for graphql-ruby on ActiveRecord
+summary: Transparent libpq pipelining for graphql-ruby on ActiveRecord, plus batch
+  loaders for plain AR
 test_files: []