duel-postgresql 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b059d32bfc73bf0bad50a8df7cb8f8aa30351001d91eb1f996d5dd66b76da775
+  data.tar.gz: e7d114e18e4f85175936566dac86065dd9c679e574901c857a8210f931b2dd5a
+SHA512:
+  metadata.gz: 14ace51e70cd9a0d5313e371cd22a7afab64f5b18cd866d002e6472971b68d120237a11b8f6bd49b309b3fb3e1e2f1dd9e9191747327590bdd0f805c1bc24c37
+  data.tar.gz: e5e1a8bafafafdce2180812c8efa763948065fdbe2c9819a9ab24f91a278a8472e6a979fc876cc81d231a311fe7de31aaa7b99e45d5132b43609cad170ca2d21

data/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-24
+
+The first release. duel-postgresql is a Duel plugin, open source under
+the MIT license, and needs Duel 0.1, Ruby 3.4 or later (CRuby, or
+TruffleRuby 40: the pg gem is a C extension), and PostgreSQL 14 or
+later, with `pg_stat_statements`.
+
+### Added
+
+- `c.use :postgresql`: a PostgreSQL server for each Duel worker,
+  on a Unix socket, its cluster copied from one made once (with Duel's
+  `w.cached`, in the project's `tmp/duel/cache`), and
+  the `postgres_queries`, `postgres_rows`, `postgres_blocks` and
+  `postgres_time` metrics, from `pg_stat_statements`, as running totals
+  (`c.metric`).
+- `Duel::PostgreSQL.url`, `Duel::PostgreSQL.execute` and
+  `Duel::PostgreSQL.reset`, for benchmarks: `execute` and `reset` open a
+  connection of their own, from the worker's `DUEL_POSTGRESQL_URL`.
+  They're for `setup` hooks, and `once` and `untimed` blocks: while a
+  benchmark is measured (`Duel.measuring?`) they raise `Duel::Error`, as what they run
+  would be counted.
+- Each worker's server's URL is in `DUEL_POSTGRESQL_URL`, and in
+  `DATABASE_URL` too, by default (`env:`). It names its user in its
+  query, `postgres:///duel?host=...&port=5432&user=postgres`, so that
+  Rails, which parses `DATABASE_URL` with Ruby's URI, boots with it
+  (duel-rails with `database: :postgresql`).
+- A regression is explained by the statements that did the most of it,
+  on each version (Duel's `details`): how many times each ran an
+  iteration, for `postgres_queries`, and their shares, for the rest.
+- `postgres_time` is in µs (`unit: "µs"`), shown as time.
+  `postgres_queries`, `postgres_rows` and `postgres_blocks` are in
+  queries, rows and blocks (`unit:`, each with its plural), so reports
+  read "1 query → 2 queries".
+- `postgres_blocks` and `postgres_time` are `kind: :ratio` measures, and
+  `postgres_time` is left out of Duel's across-the-board check
+  (`across: false`).
+- A query sent with the extended protocol (as Active Record sends
+  every one) inside a transaction is counted as it runs, not as the
+  connection's next statement does: before each reading, every
+  connection of the worker's left idle in a transaction has its unnamed
+  portal closed. So an iteration's last query, inside an
+  `around_iteration` hook's transaction (duel-rails's
+  `Duel::Rails::ROLLBACK`), is the iteration's, and the hook's `BEGIN`
+  and `ROLLBACK` aren't.
+- `c.use :postgresql` returns the plugin's own connection, opened
+  in each worker (`c.in_worker`) and closed as it ends (`at_stop`). Its
+  `value` fails outside a worker. The module keeps no connection.
+- Built on Duel's plugin API: the server is spawned and set up with
+  `Duel::Resource#spawn` and `#run`, its measures can be tuned or
+  skipped like any (`c.measure("postgres_time", limit: 1.1)`), and its tests
+  use `duel/testing`.
+- Its metrics are costly to read (Duel's `costly`): a benchmark with an
+  `around_iteration` hook reads the server's statistics only as each
+  sample starts and stops, not twice an iteration, and what the hook
+  sends the server (a transaction's `BEGIN` and `ROLLBACK`, say) is
+  learned in each worker and subtracted.
+- A reading of `pg_stat_statements` makes numbers only for the
+  statements that changed since the last reading, and shares the rest
+  with it, and a sample's statements are told from those that changed
+  alone. pg decodes the counts and times (a type map), so no String is
+  made for a number. Reading 2,000 statements, 10 of them changed,
+  allocates 26 objects.
+- Mutation tested: mutant kills every change to the plugin's code, in
+  CI.
+- RBS signatures in sig/, checked with Steep.
+
+[Unreleased]: https://github.com/sferik/duel-ruby/compare/duel-postgresql-v0.1.0...HEAD
+[0.1.0]: https://github.com/sferik/duel-ruby/releases/tag/duel-postgresql-v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erik Berlin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# duel-postgresql
+
+[![Duel](https://raw.githubusercontent.com/sferik/duel-ruby/main/assets/badge.svg)](https://github.com/sferik/duel-ruby)
+[![duel-postgresql](https://github.com/sferik/duel-ruby/actions/workflows/plugin-postgresql.yml/badge.svg)](https://github.com/sferik/duel-ruby/actions/workflows/plugin-postgresql.yml)
+[![Gem Version](https://badge.fury.io/rb/duel-postgresql.svg)](https://rubygems.org/gems/duel-postgresql)
+
+A [Duel](https://github.com/sferik/duel-ruby) plugin for code that talks
+to PostgreSQL: each Duel worker gets a PostgreSQL server of its own, and
+every benchmark is judged on what PostgreSQL did for it too.
+
+| Metric | What it is | A regression |
+|---|---|---|
+| `postgres_queries` | the statements it ran (`BEGIN` and `COMMIT` too) | any increase |
+| `postgres_rows` | the rows they returned or changed | any increase |
+| `postgres_blocks` | the shared buffer blocks they touched, cached or not | judged like CPU time |
+| `postgres_time` | the time it spent planning and running them, in µs | judged like CPU time |
+
+So a change that adds a query per record (an N+1), or fetches rows it
+doesn't use, fails even when its CPU time on the Ruby side doesn't
+change. One that stops a query using an index fails on the blocks it
+reads instead. Blocks are nearly the same from run to run, but not
+quite (a table that's updated grows, say), so they're judged like time,
+on paired ratios, not counted.
+
+A regression says which statements did it: under each version's
+numbers, the three that did the most of that measure (Duel's
+`details`), with how many times each ran an iteration for
+`postgres_queries`, and their shares of it for the rest:
+
+```
+postgres_queries: 2 queries → 6 queries an iteration
+postgres_queries (candidate): an iteration: 5× SELECT count(*) FROM comments WHERE post_id = $1; 1× SELECT * FROM posts
+postgres_queries (baseline): an iteration: 1× SELECT * FROM comments WHERE post_id = ANY($1); 1× SELECT * FROM posts
+```
+
+They're of the sample the numbers came from, but for its `untimed`
+blocks, if it has any. Queries, rows and blocks are counted in their
+units (`1 query`, `12 rows`, though the summary line leaves out the one
+a name ends in: `postgres_rows 12→40`), and `postgres_time` is shown as time
+(`postgres_time: 412µs → 1.31ms an iteration`).
+
+## Installation
+
+```ruby
+# Gemfile
+group :development do
+  gem "duel-postgresql"
+end
+```
+
+> [!NOTE]
+> It needs PostgreSQL 14 or later, with `pg_stat_statements` (it's in
+> PostgreSQL's contrib, which most packages include), and the
+> [pg](https://github.com/ged/ruby-pg) gem, so CRuby or TruffleRuby.
+
+## Usage
+
+```ruby
+# .duel.rb
+Duel.configure { |c| c.use :postgresql }
+```
+
+`c.use` requires the plugin, so `.duel.rb` doesn't need to.
+
+Each worker's server listens only on a Unix socket in the worker's own
+directory, with nothing written to disk that needn't be, and no
+autovacuum (which would change what a query reads, and its plan, while
+it's measured). Its URL is in `DUEL_POSTGRESQL_URL`, and in
+`DATABASE_URL` too, and libpq's `PGHOST`, `PGPORT`, `PGUSER` and
+`PGDATABASE` point at it, so a client that reads any of them finds it
+and nothing reaches another database. Benchmarks can call
+`Duel::PostgreSQL.url`, `Duel::PostgreSQL.execute` and
+`Duel::PostgreSQL.reset` (each of these two opens a connection of its
+own, from the worker's `DUEL_POSTGRESQL_URL`, and closes it).
+
+> [!IMPORTANT]
+> `execute` and `reset` are for setting up: call them in a `setup` hook,
+> or a `once` or `untimed` block. While a benchmark is measured (`Duel.measuring?`) they
+> raise `Duel::Error`, rather than have what they run counted.
+
+```ruby
+# duel/orders_duel.rb
+setup do
+  Duel::PostgreSQL.reset                           # empties every table
+  Duel::PostgreSQL.execute("INSERT INTO orders (total) SELECT g FROM generate_series(1, 100) g")
+  @store = OrderStore.new(Duel::PostgreSQL.url)    # its URL
+end
+
+duel("orders: the largest ten") { @store.largest(10) }
+```
+
+Options:
+
+```ruby
+c.use :postgresql,
+  bin: "/usr/lib/postgresql/17/bin",       # its programs (default: DUEL_POSTGRESQL_BIN, or found)
+  settings: {work_mem: "64MB"},             # more of its settings
+  setup: File.read("db/structure.sql"),     # SQL each worker's database runs first
+  env: %w[DATABASE_URL PRIMARY_URL]        # variables given its URL besides DUEL_POSTGRESQL_URL
+```
+
+> [!WARNING]
+> `env` matters with another plugin that sets `DATABASE_URL`
+> (`duel-mysql`, say): two prepare blocks that set a variable differently
+> fail, so give one of them other names (`env: %w[PRIMARY_URL]`, or
+> `env: []`).
+
+`bin` is found as the directory of the `postgres` on the `PATH`, links
+followed (Homebrew's `initdb` on the `PATH` may be libpq's, of another
+version), or Debian's newest under `/usr/lib/postgresql`.
+
+A database cluster takes `initdb`, and that's slow, so it's done once
+(Duel's `w.cached`): the first worker to start makes one, with the
+`duel` database and `pg_stat_statements` created in it, in your
+project's `tmp/duel/cache`, and every worker (in that run and the next
+ones) starts with a copy. One is made for each server's programs (and
+version of the plugin): another PostgreSQL gets its own. `duel --clean`
+deletes them.
+
+The metrics come from `pg_stat_statements`, which PostgreSQL updates as
+each statement ends, before its client hears it has, read by statement
+over a connection of the plugin's own, opened as each worker starts
+(Duel's `c.in_worker`, and closed as it ends): running totals (Duel's
+`c.metric`). `c.use` returns that connection, for a `.duel.rb` that
+reads the server too (`connection.value`, in a worker only). The
+reading's own statement is left out (by its query id), so there's
+nothing to take away (`calibrate: false`). `postgres_time` counts
+planning too (`pg_stat_statements.track_planning`), as a change that
+stops reusing prepared statements plans every time. Up to 10,000
+distinct statements are kept: a benchmark that makes more (with `IN`
+lists of every length, say) loses the oldest, and its counts with them.
+
+`postgres_time` is the server's time on the clock, not CPU time, and
+another process's, so what else the machine does shows in it: it's
+judged for each benchmark, but left out of Duel's across-the-board
+check (`across: false`), whose margin is a quarter of its limit.
+
+Like any measure, each can be tuned or left out in `.duel.rb`:
+`c.measure("postgres_time", limit: 1.1)`,
+`c.measure("postgres_rows", skip: true)`.

data/lib/duel/postgresql/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Duel
+  module PostgreSQL
+    VERSION = "0.1.0"
+  end
+end

data/lib/duel/postgresql.rb

@@ -0,0 +1,415 @@
+# frozen_string_literal: true
+
+require "duel"
+require "digest"
+require "fileutils"
+require "pg"
+require_relative "postgresql/version"
+
+module Duel
+  # A PostgreSQL server of each worker's own, and what it did for each
+  # benchmark, from pg_stat_statements:
+  #
+  # - postgres_queries: the statements it ran (counted)
+  # - postgres_rows: the rows they returned or changed (counted)
+  # - postgres_blocks: the shared buffer blocks they touched, from the
+  #   cache or not (judged like CPU time: nearly steady, but a table
+  #   that grows, say, takes more)
+  # - postgres_time: the time it spent planning and running them, in
+  #   microseconds (judged like CPU time)
+  #
+  # Where one regressed, it says which statements did the most of it, on
+  # each version (Statements#details).
+  #
+  #   # .duel.rb
+  #   Duel.configure { |c| c.use :postgresql }
+  #
+  # Benchmarks can call Duel::PostgreSQL.url, and .execute and .reset in
+  # setup (or untimed blocks): while a benchmark is measured, they fail.
+  #
+  # The server listens only on a Unix socket in the worker's directory;
+  # its URL is in DUEL_POSTGRESQL_URL, and in DATABASE_URL too (unless
+  # +env+ names others), and libpq's PGHOST, PGPORT, PGUSER and
+  # PGDATABASE point at it, so a client finds it and nothing reaches
+  # another database.
+  module PostgreSQL
+    Duel.plugin(:postgresql, self)
+
+    URL = "DUEL_POSTGRESQL_URL"
+    DATABASE = "duel"
+    USER = "postgres"
+    # It names the socket (.s.PGSQL.5432): the server listens on no port.
+    PORT = 5432
+
+    # The server's settings: nothing to disk that needn't be, nothing
+    # running on its own (autovacuum would change what a query touches,
+    # and its plan, while it's measured), and pg_stat_statements.
+    SETTINGS = {
+      "listen_addresses" => "",
+      "fsync" => "off",
+      "synchronous_commit" => "off",
+      "full_page_writes" => "off",
+      "autovacuum" => "off",
+      "jit" => "off",
+      "shared_buffers" => "32MB",
+      "shared_preload_libraries" => "pg_stat_statements",
+      "compute_query_id" => "on",
+      "pg_stat_statements.max" => "10000",
+      "pg_stat_statements.track_planning" => "on"
+    }.freeze
+
+    # Configures Duel for the plugin (c.use :postgresql): the server and
+    # its metrics. +bin+ is the directory of its programs (postgres and
+    # initdb: by default, the real directory of the postgres on the
+    # PATH), +settings+ more of its settings, +setup+ SQL each worker's
+    # database runs when it's started (a schema, say), and +env+ the
+    # variables given its URL besides DUEL_POSTGRESQL_URL. A cluster is
+    # initdb'd once (Resource#cached), and each worker's is a copy.
+    # Returns the plugin's own connection to it, a worker's (see
+    # Config#in_worker, and in tests, Duel::Testing.in_worker).
+    def self.configure(config, bin: ENV.fetch("DUEL_POSTGRESQL_BIN", nil), settings: {}, setup: nil, env: %w[DATABASE_URL])
+      config.prepare(:worker) do |w|
+        programs = File.expand_path(bin || Cluster.find_bin ||
+          w.failed("no postgres on the PATH (give its directory as bin:, or DUEL_POSTGRESQL_BIN)"))
+        data = w.path("data")
+        Cluster.new(w, programs).create(data)
+        # (Stopped by INT: its clients are disconnected, not waited for, as
+        # TERM would.)
+        # (Of a setting given twice, postgres takes the last: +settings+'.)
+        w.spawn(File.join(programs, "postgres"), "-D", data, "-k", w.dir, "-p", PORT.to_s,
+          *SETTINGS.merge(settings).flat_map { |name, value| ["-c", "#{name}=#{value}"] }, stop_signal: "INT")
+        # (The user in the query, with no authority at all: Ruby's URI, which
+        # Rails parses DATABASE_URL with, takes a user without a host for
+        # a malformed host.)
+        url = "postgres:///#{DATABASE}?host=#{w.dir}&port=#{PORT}&user=#{USER}"
+        w.wait_until { PG::Connection.ping(url) == PG::PQPING_OK }
+        run(url, setup) if setup
+        {URL => url, "PGHOST" => w.dir, "PGPORT" => PORT.to_s, "PGUSER" => USER, "PGDATABASE" => DATABASE}
+          .merge(env.to_h { |name| [name, url] })
+      end
+      # (In the worker, libpq's environment is its server's.)
+      connection = config.in_worker { |w| PG.connect.tap { |pg| w.at_stop { pg.close } } }
+      statements = Statements.new(connection)
+      config.metric(METRICS) { statements.read }.costly.details { |stretches, sample| statements.details(stretches, sample.n) }
+      connection
+    end
+
+    # Runs SQL on a connection of its own to +url+; returns the last
+    # statement's result. (async_exec is exec, by its other name: one a
+    # mutation can't make Kernel#exec.)
+    def self.run(url, sql)
+      connection = PG.connect(url)
+      begin
+        connection.async_exec(sql)
+      ensure
+        connection.close
+      end
+    end
+
+    # Server time isn't the worker's CPU time: another process's, on the
+    # clock, so what else the machine does shows in it. It's judged on
+    # each benchmark, but left out across the board, where the margin is
+    # too small for it. Its readings leave themselves out (STATEMENTS), so
+    # there's nothing to take away.
+    METRICS = {
+      "postgres_queries" => {kind: :counted, unit: %w[query queries], calibrate: false},
+      "postgres_rows" => {kind: :counted, unit: %w[row rows], calibrate: false},
+      "postgres_blocks" => {kind: :ratio, unit: %w[block blocks], floor: 100, sizes_samples: false},
+      "postgres_time" => {kind: :ratio, unit: "µs", floor: 300, across: false}
+    }
+
+    # What the worker's server has done so far, by statement (query id),
+    # but for these readings themselves (their statement is left out by
+    # its query id), so nothing's left to take away. pg_stat_statements
+    # is updated as each statement ends, before the client hears it has
+    # (but for one left open in a transaction: see .settle).
+    STATEMENTS = <<~SQL
+      SELECT queryid, sum(calls), sum(rows), sum(shared_blks_hit + shared_blks_read), sum(total_plan_time + total_exec_time)
+      FROM pg_stat_statements
+      WHERE queryid IS DISTINCT FROM (SELECT query_id FROM pg_stat_activity WHERE pid = pg_backend_pid())
+      GROUP BY queryid
+    SQL
+
+    # STATEMENTS' columns, as pg decodes them: the query id as text, the
+    # counts as Integers and the time (ms) as a Float, with no String
+    # made for a number only to be parsed.
+    COLUMNS = PG::TypeMapByColumn.new([nil, PG::TextDecoder::Integer.new, PG::TextDecoder::Integer.new,
+      PG::TextDecoder::Integer.new, PG::TextDecoder::Float.new])
+
+    # Statements' texts, by query id (a PostgreSQL array of them).
+    TEXTS = "SELECT DISTINCT ON (queryid) queryid, coalesce(query, '') FROM pg_stat_statements WHERE queryid = ANY($1::bigint[])"
+
+    # What the worker's server has done so far, by statement, read over
+    # +connection+ (the plugin's own): a column each of their query ids,
+    # queries, rows, blocks and time (ms), a statement to a row.
+    def self.columns(connection)
+      settle
+      # (None is NULL: every statement has a query id.)
+      result = connection.async_exec(STATEMENTS).map_types!(COLUMNS)
+      [result.column_values(0), result.column_values(1), result.column_values(2), result.column_values(3), result.column_values(4)]
+    end
+
+    # The empty query's parameters (see .settle).
+    NO_PARAMS = [] #: Array[String]
+    NO_PARAMS.freeze
+
+    # Ends the statement each of the process's +connections+ (the
+    # benchmark's, the app's) has left open in a transaction, for a
+    # reading to count it. pg_stat_statements counts a statement as its
+    # executor ends, and one sent with the extended protocol (pg's
+    # exec_params and exec_prepared, so every query of Active Record's)
+    # keeps its executor open, in the unnamed portal, until the
+    # connection's next statement, or its transaction's end. Inside an
+    # around_iteration hook's transaction, an iteration's last query
+    # would be counted only as the hook's ROLLBACK ran, as the hook's.
+    # Closing the portal (libpq 17's Close, or before it, an empty query,
+    # which takes its place) ends it, and counts nothing of its own. One
+    # outside a transaction, busy, or in a failed one has none to end.
+    def self.settle(connections = ObjectSpace.each_object(PG::Connection))
+      connections.each do |pg|
+        next if pg.finished? || pg.transaction_status != PG::PQTRANS_INTRANS
+
+        pg.respond_to?(:close_portal) ? pg.close_portal("") : pg.exec_params("", NO_PARAMS)
+      end
+    end
+
+    # What the worker's server has done so far, by statement, read over
+    # +connection+: each one's [queries, rows, blocks, time (ns)], by
+    # query id.
+    def self.statements(connection)
+      ids, calls, rows, blocks, ms = columns(connection)
+      ids.each_with_index.to_h { |id, i| [id, [calls.fetch(i), rows.fetch(i), blocks.fetch(i), ns(ms.fetch(i))]] }
+    end
+
+    # A time in ms (pg_stat_statements'), in ns.
+    def self.ns(ms) = (ms * 1_000_000).round
+
+    # What the worker's server has done so far, all told, by measure, read
+    # over +connection+.
+    def self.stats(connection) = Statements.total(statements(connection).values)
+
+    # The texts of the statements with these query ids, by query id
+    # (normalized: $1 for each constant), read over +connection+.
+    def self.texts(connection, ids)
+      connection.exec_params(TEXTS, ["{#{ids.join(",")}}"]).values.to_h
+    end
+
+    # For benchmarks: the worker's server.
+    def self.url = ENV.fetch(URL)
+
+    # Runs SQL (statements, ;-separated) on it, over a connection of its
+    # own; returns the last one's result. For setting up: it fails while
+    # a benchmark is measured (Duel.measuring?), as what it runs would be
+    # counted.
+    def self.execute(sql)
+      Duel.unmeasured!("Duel::PostgreSQL.execute")
+      run(url, sql)
+    end
+
+    # Empties every table (but PostgreSQL's own), restarting their
+    # sequences. For setting up, as execute is.
+    def self.reset
+      Duel.unmeasured!("Duel::PostgreSQL.reset")
+      run(url, RESET)
+    end
+
+    # What reset runs.
+    RESET = <<~SQL
+      DO $$
+      DECLARE tables text;
+      BEGIN
+        SELECT string_agg(format('%I.%I', schemaname, tablename), ', ') INTO tables
+          FROM pg_tables WHERE schemaname NOT IN ('pg_catalog', 'information_schema');
+        IF tables IS NOT NULL THEN
+          EXECUTE 'TRUNCATE ' || tables || ' RESTART IDENTITY CASCADE';
+        END IF;
+      END $$
+    SQL
+
+    # Running totals of what the worker's server did, all told (#read),
+    # and by statement, to explain a regression with the statements that
+    # did the most of it (#details). A reading makes numbers only for the
+    # statements that changed since the last one, and a sample's are told
+    # from those: the rest are the last reading's.
+    class Statements
+      # The measures, in the order of a statement's numbers.
+      NAMES = METRICS.keys.freeze
+
+      # The statements a regression is explained with, and how much of
+      # each one's text.
+      SHOWN = 3
+      TEXT = 80
+
+      # A statement that did nothing yet.
+      NOTHING = [0, 0, 0, 0].freeze
+
+      # A reading's context: every statement's numbers, by query id (a
+      # Hash it shares with the last reading, if none changed), the last
+      # reading's, and the query ids of those that changed since.
+      Reading = Data.define(:numbers, :previous, :changed)
+
+      # Statements' numbers, all told, by measure (time in µs).
+      def self.total(statements) = by_measure(sum(statements))
+
+      # Statements' numbers, added up.
+      def self.sum(statements) = NAMES.each_index.map { |i| statements.sum { |numbers| numbers.fetch(i) } }
+
+      # A statement's numbers, or several's added up, by measure (time in
+      # µs).
+      def self.by_measure(numbers)
+        NAMES.each_with_index.to_h { |name, i| [name, (name == "postgres_time") ? numbers.fetch(i).fdiv(1000) : numbers.fetch(i)] }
+      end
+
+      # Read over +connection+, the plugin's own (a worker's).
+      def initialize(connection)
+        @connection = connection
+        @texts = {} # (each statement's, once)
+        # (The last reading's numbers, and theirs added up.)
+        @numbers = {} #: Hash[String, numbers]
+        @sums = NOTHING.dup
+      end
+
+      # What the server has done so far, all told, by measure, and by
+      # statement (the reading's context, a Reading, for #details).
+      def read
+        ids, calls, rows, blocks, ms = PostgreSQL.columns(@connection.value)
+        previous = @numbers
+        numbers = previous
+        changed = [] #: Array[String]
+        ids.each_with_index do |id, i|
+          was = previous[id]
+          time = PostgreSQL.ns(ms.fetch(i))
+          next if was && was.fetch(0) == calls.fetch(i) && was.fetch(1) == rows.fetch(i) && was.fetch(2) == blocks.fetch(i) &&
+            was.fetch(3) == time
+
+          # (The last reading's Hash is its own: copied, at the first change.)
+          numbers = previous.dup if numbers.equal?(previous)
+          now = numbers[id] = [calls.fetch(i), rows.fetch(i), blocks.fetch(i), time]
+          changed << id
+          was ||= NOTHING
+          NAMES.each_index { |n| @sums[n] += now.fetch(n) - was.fetch(n) }
+        end
+        numbers = forget(numbers, ids) if numbers.size > ids.size
+        @numbers = numbers.freeze
+        [Statements.by_measure(@sums), Reading.new(numbers, previous, changed)]
+      end
+
+      # The statements that did the most of each measure in a sample's
+      # stretches (pairs of #read's readings: see Snapshot#details), by
+      # measure: how many times each ran an iteration (+n+ of them), "an
+      # iteration: 2× SELECT name FROM items WHERE id = $1", and each
+      # one's share of the rest, "SELECT name FROM items WHERE id = $1
+      # (75%)".
+      def details(stretches, n)
+        grew = grew(stretches)
+        texts = texts(grew.keys)
+        NAMES.each_with_index.filter_map do |name, i|
+          top = grew.filter_map { |id, more| [more.fetch(i), texts.fetch(id, id)] if more.fetch(i).positive? } #: Array[[Integer, String]]
+          next if top.empty?
+
+          shown = top.sort_by { |value, text| [-value, text] }.first(SHOWN)
+          told = if i.zero? # (queries)
+            "an iteration: #{shown.map { |value, text| "#{format("%.4g", value.fdiv(n))}× #{text}" }.join("; ")}"
+          else
+            all = top.sum { |value, _| value }
+            shown.map { |value, text| "#{text} (#{format("%.3g%%", value * 100.0 / all)})" }.join("; ")
+          end
+          [name, told]
+        end.to_h
+      end
+
+      private
+
+      # What each statement did in the +stretches+, all told, by query
+      # id: those that did anything.
+      def grew(stretches)
+        grew = {} #: Hash[String, numbers]
+        stretches.each do |started, stopped|
+          before = started.context.numbers
+          after = stopped.context
+          # (Read right after +started+, it says which changed since: the
+          # others can't have done anything.)
+          ids = after.previous.equal?(before) ? after.changed : after.numbers.keys
+          ids.each do |id|
+            now = after.numbers.fetch(id)
+            was = before.fetch(id, NOTHING)
+            so_far = grew.fetch(id, NOTHING)
+            grew[id] = Array.new(now.size) { |i| so_far.fetch(i) + now.fetch(i) - was.fetch(i) }
+          end
+        end
+        grew.select { |_, more| more.any?(&:positive?) }
+      end
+
+      # The +numbers+ of the statements with these query ids (+ids+, of
+      # every statement in pg_stat_statements: those gone, the oldest past
+      # pg_stat_statements.max, or every one after a reset, forgotten),
+      # and their sums.
+      def forget(numbers, ids)
+        kept = numbers.slice(*ids)
+        @sums = Statements.sum(kept.values)
+        kept
+      end
+
+      # Each statement's text, squeezed onto a line, by query id: those
+      # not yet known read from the server.
+      def texts(ids)
+        unknown = ids.reject { |id| @texts.key?(id) }
+        PostgreSQL.texts(@connection.value, unknown).each { |id, query| @texts[id] = shorten(query.split.join(" ")) } unless unknown.empty?
+        @texts
+      end
+
+      def shorten(text) = (text.length > TEXT) ? "#{text[0, TEXT - 1]}…" : text
+    end
+
+    # A worker's database cluster: a copy of one initdb'd once, with the
+    # database and pg_stat_statements created in it.
+    class Cluster
+      # The real directory of the postgres on +path+ (where its initdb is:
+      # the one on the PATH may be another version's, libpq's, say), or of
+      # the newest Debian's; nil if there's none.
+      def self.find_bin(path = ENV.fetch("PATH", ""), debian: "/usr/lib/postgresql/*/bin")
+        postgres = path.split(File::PATH_SEPARATOR).map { |dir| File.join(dir, "postgres") }.find { |file| File.executable?(file) }
+        return File.dirname(File.realpath(postgres)) if postgres
+
+        Dir[debian].max_by { |dir| File.basename(File.dirname(dir)).to_i }
+      end
+
+      def initialize(resource, bin)
+        @resource = resource
+        @bin = bin
+      end
+
+      # Makes one in +data+: a copy of the one made for these programs.
+      def create(data)
+        FileUtils.cp_r(@resource.cached(key) { |dir| make(dir) }, data)
+        File.chmod(0o700, data) # (as postgres insists)
+      end
+
+      private
+
+      # What a cluster is good for: these programs (until they change),
+      # and this version of the plugin.
+      def key
+        postgres = File.realpath(File.join(@bin, "postgres"))
+        "postgresql-#{VERSION}-#{Digest::SHA256.hexdigest([postgres, File.mtime(postgres).to_f].join("\0"))[0, 16]}"
+      end
+
+      def make(data)
+        run("initdb", "--pgdata=#{data}", "-U", USER, "-A", "trust", "-E", "UTF8", "--locale=C", "--no-sync")
+        single(data, "postgres", "CREATE DATABASE #{DATABASE}")
+        single(data, DATABASE, "CREATE EXTENSION pg_stat_statements")
+      end
+
+      # Runs a statement in the cluster's +database+, in single-user mode:
+      # no server to start, and stop.
+      def single(data, database, sql)
+        input = @resource.path("single.sql")
+        File.write(input, "#{sql}\n")
+        run("postgres", "--single", "-D", data, "-c", "exit_on_error=on", database, in: input)
+      end
+
+      # Runs one of the programs (to its end), logged as its name.
+      def run(program, *args, **options) = @resource.run(File.join(@bin, program), *args, **options)
+    end
+  end
+end

data/sig/duel/postgresql.rbs

@@ -0,0 +1,178 @@
+module Duel
+  # A PostgreSQL server of each worker's own, and what it did for each
+  # benchmark (postgres_queries, postgres_rows, postgres_blocks,
+  # postgres_time).
+  module PostgreSQL
+    VERSION: String
+
+    URL: String
+    DATABASE: String
+    USER: String
+
+    # It names the socket: the server listens on no port.
+    PORT: Integer
+
+    # The server's settings.
+    SETTINGS: Hash[String, String]
+
+    METRICS: Hash[String, Metric::settings]
+
+    # What the worker's server has done so far, by statement, but for
+    # these readings.
+    STATEMENTS: String
+
+    # STATEMENTS' columns, as pg decodes them.
+    COLUMNS: ::PG::TypeMapByColumn
+
+    # Statements' texts, by query id.
+    TEXTS: String
+
+    # A statement's numbers: queries, rows, blocks, time (ns).
+    type numbers = Array[Integer]
+
+    # Configures Duel for the plugin (c.use :postgresql): the server
+    # (+bin+ the directory of its programs, +settings+ more of its
+    # settings, +setup+ SQL each worker's database runs when it's started,
+    # +env+ the variables besides DUEL_POSTGRESQL_URL given its URL) and
+    # its metrics. Returns the plugin's own connection to it, a worker's.
+    def self.configure: (Config config, ?bin: String?, ?settings: Hash[String | Symbol, String | Integer], ?setup: String?,
+                         ?env: Array[String]) -> InWorker[::PG::Connection]
+
+    # Runs SQL on a connection of its own to +url+; returns the last
+    # statement's result.
+    def self.run: (String url, String sql) -> ::PG::Result
+
+    # The empty query's parameters (see .settle).
+    NO_PARAMS: Array[String]
+
+    # Ends the statement each of the process's +connections+ has left
+    # open in a transaction, for a reading to count it.
+    def self.settle: (?Enumerable[::PG::Connection] connections) -> void
+
+    # What the worker's server has done so far, by statement, read over
+    # +connection+: a column each of their query ids, queries, rows,
+    # blocks and time (ms).
+    def self.columns: (::PG::Connection connection) -> [Array[String], Array[Integer], Array[Integer], Array[Integer], Array[Float]]
+
+    # What the worker's server has done so far, by statement (query id),
+    # read over +connection+.
+    def self.statements: (::PG::Connection connection) -> Hash[String, numbers]
+
+    # A time in ms, in ns.
+    def self.ns: (Float ms) -> Integer
+
+    # What the worker's server has done so far, all told, read over
+    # +connection+.
+    def self.stats: (::PG::Connection connection) -> Snapshot::totals[Metric::value]
+
+    # The texts of the statements with these query ids, by query id, read
+    # over +connection+.
+    def self.texts: (::PG::Connection connection, Array[String] ids) -> Hash[String, String]
+
+    # For benchmarks: the worker's server.
+    def self.url: () -> String
+
+    # Runs SQL on it, over a connection of its own; returns the last
+    # statement's result. For setting up: it fails while a benchmark is
+    # measured.
+    def self.execute: (String sql) -> ::PG::Result
+
+    # Empties every table, restarting their sequences. For setting up,
+    # as execute is.
+    def self.reset: () -> ::PG::Result
+
+    # What reset runs.
+    RESET: String
+
+    # Running totals of what the worker's server did, all told, and by
+    # statement, to explain a regression.
+    class Statements
+      # The measures, in the order of a statement's numbers.
+      NAMES: Array[String]
+
+      # The statements a regression is explained with, and how much of
+      # each one's text.
+      SHOWN: Integer
+      TEXT: Integer
+
+      # A statement that did nothing yet.
+      NOTHING: numbers
+
+      # A reading's context: every statement's numbers, by query id, the
+      # last reading's, and the query ids of those that changed since.
+      class Reading < Data
+        attr_reader numbers: Hash[String, numbers]
+        attr_reader previous: Hash[String, numbers]
+        attr_reader changed: Array[String]
+
+        def self.new: (Hash[String, numbers] numbers, Hash[String, numbers] previous, Array[String] changed) -> Reading
+      end
+
+      @connection: InWorker[::PG::Connection]
+      @texts: Hash[String, String]
+      @numbers: Hash[String, numbers]
+      @sums: numbers
+
+      # Statements' numbers, all told, by measure.
+      def self.total: (Array[numbers] statements) -> Snapshot::totals[Metric::value]
+
+      # Statements' numbers, added up.
+      def self.sum: (Array[numbers] statements) -> numbers
+
+      # A statement's numbers, or several's added up, by measure.
+      def self.by_measure: (numbers numbers) -> Snapshot::totals[Metric::value]
+
+      # Read over +connection+, the plugin's own (a worker's).
+      def initialize: (InWorker[::PG::Connection] connection) -> void
+
+      # What the server has done so far, all told, by measure, and by
+      # statement (the reading's context, for #details).
+      def read: () -> [Snapshot::totals[Metric::value], Reading]
+
+      # The statements that did the most of each measure in a sample's
+      # stretches, by measure: how many times each ran an iteration (+n+
+      # of them), and each one's share of the rest.
+      def details: (Snapshot::stretches[Metric::value, Reading] stretches, Integer n) -> Hash[String, String]
+
+      private
+
+      # What each statement did in the stretches, all told, by query id.
+      def grew: (Snapshot::stretches[Metric::value, Reading] stretches) -> Hash[String, numbers]
+
+      # The +numbers+ of the statements with these query ids, those gone
+      # forgotten, and their sums.
+      def forget: (Hash[String, numbers] numbers, Array[String] ids) -> Hash[String, numbers]
+
+      # Each statement's text, by query id.
+      def texts: (Array[String] ids) -> Hash[String, String]
+
+      def shorten: (String text) -> String
+    end
+
+    # A worker's database cluster: a copy of one initdb'd once.
+    class Cluster
+      @resource: Resource
+      @bin: String
+
+      # The real directory of the postgres on +path+, or of the newest
+      # Debian's; nil if there's none.
+      def self.find_bin: (?String path, ?debian: String) -> String?
+
+      def initialize: (Resource resource, String bin) -> void
+
+      # Makes one in +data+: a copy of the one made for these programs.
+      def create: (String data) -> void
+
+      private
+
+      def key: () -> String
+
+      def make: (String data) -> void
+
+      def single: (String data, String database, String sql) -> void
+
+      # Runs one of the programs to its end.
+      def run: (String program, *String args, **untyped options) -> void
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: duel-postgresql
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Erik Berlin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: duel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: 'A Duel plugin: each worker gets a PostgreSQL server of its own, and
+  every benchmark is judged on the queries it sent, the rows they returned, the buffers
+  they touched and their time too.'
+email:
+- sferik@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/duel/postgresql.rb
+- lib/duel/postgresql/version.rb
+- sig/duel/postgresql.rbs
+homepage: https://github.com/sferik/duel-ruby/tree/main/plugins/postgresql
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/sferik/duel-ruby/tree/main/plugins/postgresql
+  changelog_uri: https://github.com/sferik/duel-ruby/blob/main/plugins/postgresql/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sferik/duel-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: A PostgreSQL server for each Duel worker, and what it did for each benchmark
+test_files: []