duel-mysql 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dbe9a6c464029e259d365dbd4592760e1341e6f1bcc4f8d202ea3c16a884f514
+  data.tar.gz: 493b672d01e30c73936dc7460f1b464cc88a9e71cbb9050cc4b3c8ce70f6a808
+SHA512:
+  metadata.gz: 924c9565a2f71df2002086bf3a5906d3fedfd4a222081e009ff3824aee26344dfee15cc4fddcc3358656aa5528b28a44e36cb2923b2335da8c017e122b4c422b
+  data.tar.gz: cc290806a425dd3b52e48278640a85f18e573a35537e965b245dc289e00ec07286d94d9dd24a1fb2ed8bfb806acb527c412cbc045aded7ea942cf2d5d9bd1fd6

data/CHANGELOG.md

@@ -0,0 +1,70 @@
+# 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-mysql is a Duel plugin, open source under the
+MIT license, and needs Duel 0.1, CRuby 3.4 or later (the trilogy gem is
+a C extension, and TruffleRuby 40.0 fails inside it), and MySQL 8.0.30
+or later (not MariaDB).
+
+### Added
+
+- `c.use :mysql`: a MySQL server for each Duel worker, on a Unix
+  socket, its data directory copied from one made once (with Duel's
+  `w.cached`, in the project's `tmp/duel/cache`), and the
+  `mysql_queries`, `mysql_rows`, `mysql_rows_examined` and `mysql_time`
+  metrics, from its status and `performance_schema`, as running totals
+  (`c.metric`).
+- `Duel::MySQL.url`, `Duel::MySQL.socket`, `Duel::MySQL.execute` and
+  `Duel::MySQL.reset`, for benchmarks: `execute` and `reset` open a
+  connection of their own, from the worker's `DUEL_MYSQL_SOCKET`.
+  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.
+- A regression is explained by the statements (by digest) that did the
+  most of it, on each version (Duel's `details`): how many times each
+  ran an iteration, for `mysql_queries`, and their shares, for the rest.
+- `mysql_time` is in µs (`unit: "µs"`), shown as time. `mysql_queries`,
+  `mysql_rows` and `mysql_rows_examined` are in queries and rows
+  (`unit:`, each with its plural), so reports read "1 query → 2
+  queries".
+- `mysql_time` is a `kind: :ratio` measure, left out of Duel's
+  across-the-board check (`across: false`).
+- `c.use :mysql` 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("mysql_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 reads only the statements that ran since the one before it
+  (by their `LAST_SEEN`, from a second before it, so one counted while
+  that one read is read again), and says which changed: explaining a
+  stretch whose readings are one right after the other looks at those
+  only, and one with a reading in between at every statement. Reading
+  and explaining a sample cost what ran in it, not every statement the
+  server has run so far. With 2000 statements and none run, the plugin's
+  Ruby for a sample (two readings and its details) takes about 8µs and
+  58 objects.
+- A reading waits for clients only, not for the event scheduler or an
+  event that's running: those whose thread shows a statement in
+  `performance_schema.threads`, or counted in `Threads_running`, less
+  the server's event threads.
+- 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-mysql-v0.1.0...HEAD
+[0.1.0]: https://github.com/sferik/duel-ruby/releases/tag/duel-mysql-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,143 @@
+# duel-mysql
+
+[![Duel](https://raw.githubusercontent.com/sferik/duel-ruby/main/assets/badge.svg)](https://github.com/sferik/duel-ruby)
+[![duel-mysql](https://github.com/sferik/duel-ruby/actions/workflows/plugin-mysql.yml/badge.svg)](https://github.com/sferik/duel-ruby/actions/workflows/plugin-mysql.yml)
+[![Gem Version](https://badge.fury.io/rb/duel-mysql.svg)](https://rubygems.org/gems/duel-mysql)
+
+A [Duel](https://github.com/sferik/duel-ruby) plugin for code that talks
+to MySQL: each Duel worker gets a MySQL server of its own, and every
+benchmark is judged on what MySQL did for it too.
+
+| Metric | What it is | A regression |
+|---|---|---|
+| `mysql_queries` | the statements clients sent it (`Questions`) | any increase |
+| `mysql_rows` | the rows they returned or changed | any increase |
+| `mysql_rows_examined` | the rows it read to run them | any increase |
+| `mysql_time` | the time it spent running them, in µs | judged like CPU time |
+
+So a change that adds a query per record (an N+1), fetches rows it
+doesn't use, or stops a query using an index (and so examines every row
+of a table) fails even when its CPU time on the Ruby side doesn't
+change.
+
+A regression says which statements did it: under each version's
+numbers, the three that did the most of that measure, by their digests
+(Duel's `details`), with how many times each ran an iteration for
+`mysql_queries`, and their shares of it for the rest:
+
+```
+mysql_rows_examined: 2 rows → 1001 rows an iteration
+mysql_rows_examined (candidate): SELECT NAME FROM `items` WHERE `id` = ? (99.9%); SELECT * FROM `users` WHERE `id` = ? (0.0999%)
+mysql_rows_examined (baseline): SELECT * FROM `users` WHERE `id` = ? (50%); SELECT NAME FROM `items` WHERE `id` = ? (50%)
+```
+
+They're of the sample the numbers came from, but for its `untimed`
+blocks, if it has any. Queries and rows are counted in their units
+(`1 query`, `2 rows`, though the summary line leaves out the one a name
+ends in: `mysql_queries 4→8`), and `mysql_time` is shown as time
+(`mysql_time: 412µs → 1.31ms an iteration`).
+
+## Installation
+
+```ruby
+# Gemfile
+group :development do
+  gem "duel-mysql"
+end
+```
+
+> [!NOTE]
+> It needs MySQL 8.0.30 or later (not MariaDB: its `performance_schema`
+> differs) and the [trilogy](https://github.com/trilogy-libraries/trilogy)
+> gem, so CRuby (TruffleRuby 40.0 fails inside trilogy once benchmarks
+> run). Your code can use any client: trilogy is only the plugin's own.
+
+## Usage
+
+```ruby
+# .duel.rb
+Duel.configure { |c| c.use :mysql }
+```
+
+`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 (no `my.cnf` is read), with no binary log, little memory,
+nothing written to disk that needn't be, and InnoDB's statistics left as
+they are (recalculated on their own, they'd change a query's plan while
+it's measured: `ANALYZE TABLE` in a setup if you need them). Its URL is
+in `DUEL_MYSQL_URL`, and in `DATABASE_URL` too, so a client that reads
+that finds it and nothing reaches another database. The socket's path
+is in `DUEL_MYSQL_SOCKET`. Benchmarks can call `Duel::MySQL.url`,
+`Duel::MySQL.socket`, `Duel::MySQL.execute` and `Duel::MySQL.reset`
+(each of these two opens a connection of its own, from the worker's
+`DUEL_MYSQL_SOCKET`, and closes it).
+
+> [!IMPORTANT]
+> `execute` and `reset` are for setting up: call them in a `setup` hook,
+> or a `once` or `untimed` block, not the code that's measured, where their statements
+> would count, as any client's. While a benchmark is measured
+> (`Duel.measuring?`) they raise `Duel::Error`.
+
+```ruby
+# duel/orders_duel.rb
+setup do
+  Duel::MySQL.reset                                  # empties every table
+  Duel::MySQL.execute("INSERT INTO orders (total) VALUES (1), (2), (3)")
+  @store = OrderStore.new(socket: Duel::MySQL.socket) # its socket
+end
+
+duel("orders: the largest ten") { @store.largest(10) }
+```
+
+Options:
+
+```ruby
+c.use :mysql,
+  server: "/usr/local/mysql/bin/mysqld",    # the program (default: DUEL_MYSQL_SERVER, or mysqld)
+  args: ["--sort-buffer-size=4M"],          # more of its options
+  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_MYSQL_URL
+  scheme: "trilogy"                         # the URL's (Rails takes it for the adapter, mysql2 by default)
+```
+
+> [!WARNING]
+> `env` matters with another plugin that sets `DATABASE_URL`
+> (`duel-postgresql`, say): two prepare blocks that set a variable differently
+> fail, so give one of them other names (`env: %w[PRIMARY_URL]`, or
+> `env: []`).
+
+Initializing a data directory takes seconds, so it's done once (Duel's
+`w.cached`): the first worker to start makes one, with the `duel`
+database 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 program (and version of the plugin): another MySQL gets
+its own. `duel --clean` deletes them. (`args` are the running server's,
+not its initialization's.)
+
+The metrics come from the server's status (`Questions`) and
+`performance_schema` (its statement summaries), which MySQL updates as
+each statement ends (MySQL 8.0's just after its client hears it has: a
+reading waits, a second at most, until no other client is running a
+statement: the server's own threads, the event scheduler's and its
+events', aren't waited for), read 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). Each
+reading takes that connection's own totals from the server's, so its statements
+are left out (and connections that have closed still count), and
+there's nothing to take away (`calibrate: false`). The
+statements a regression names come from the statement summaries by
+digest (`events_statements_summary_by_digest`), the plugin's readings
+left out: each reading reads only the statements run since the one
+before it (by their `LAST_SEEN`, from a second before it), so it costs
+what ran, not what the server has run so far.
+
+`mysql_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("mysql_time", limit: 1.1)`,
+`c.measure("mysql_rows_examined", skip: true)`.

data/lib/duel/mysql/version.rb

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

data/lib/duel/mysql.rb

@@ -0,0 +1,450 @@
+# frozen_string_literal: true
+
+require "duel"
+require "digest"
+require "fileutils"
+require "trilogy"
+require_relative "mysql/version"
+
+module Duel
+  # A MySQL server of each worker's own, and what it did for each
+  # benchmark, from its status and performance_schema:
+  #
+  # - mysql_queries: the statements clients sent it (Questions) (counted)
+  # - mysql_rows: the rows they returned or changed (counted)
+  # - mysql_rows_examined: the rows it read to run them (counted)
+  # - mysql_time: the time it spent 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 :mysql }
+  #
+  # Benchmarks can call Duel::MySQL.url and .socket, 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_MYSQL_URL, and in DATABASE_URL too (unless +env+
+  # names others), and the socket's path in DUEL_MYSQL_SOCKET.
+  module MySQL
+    Duel.plugin(:mysql, self)
+
+    URL = "DUEL_MYSQL_URL"
+    SOCKET = "DUEL_MYSQL_SOCKET"
+    DATABASE = "duel"
+    USER = "root"
+
+    # The server's options (after --no-defaults: no my.cnf of the
+    # machine's): no network, nothing to disk that needn't be, little
+    # memory, no Linux AIO contexts (there are only so many, for every
+    # server on the machine), and nothing running on its own
+    # (recalculating a table's statistics would change its plans while
+    # they're measured).
+    OPTIONS = %w[
+      --skip-networking --mysqlx=OFF --skip-log-bin
+      --innodb-buffer-pool-size=32M --innodb-redo-log-capacity=8M --innodb-doublewrite=OFF --innodb-use-native-aio=OFF
+      --innodb-flush-log-at-trx-commit=0 --innodb-stats-auto-recalc=OFF --event-scheduler=OFF --performance-schema=ON
+    ].freeze
+
+    # And once it's initialized: stopped like a crash, nothing flushed (as
+    # what's in it is thrown away).
+    RUNNING = %w[--innodb-fast-shutdown=2].freeze
+
+    # Configures Duel for the plugin (c.use :mysql): the server and its
+    # metrics. +server+ is the program, +args+ more of its options,
+    # +setup+ SQL each worker's database runs when it's started (a
+    # schema, say), +env+ the variables given its URL besides
+    # DUEL_MYSQL_URL, and +scheme+ the URL's (Rails takes it for the
+    # adapter). A data directory is initialized 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, server: ENV.fetch("DUEL_MYSQL_SERVER", "mysqld"), args: [], setup: nil, env: %w[DATABASE_URL],
+      scheme: "mysql2")
+      config.prepare(:worker) do |w|
+        program = DataDir.find_server(server) || w.failed("no #{server} on the PATH (give it as server:, or DUEL_MYSQL_SERVER)")
+        data = w.path("data")
+        DataDir.new(w, program).create(data)
+        socket = w.path("mysqld.sock")
+        w.spawn(program, *DataDir.options(data), "--socket=#{socket}", "--pid-file=#{w.path("mysqld.pid")}", "--tmpdir=#{w.dir}",
+          *(RUNNING + args))
+        w.wait_until { Connection.ping(socket) }
+        run(socket, setup) if setup
+        url = "#{scheme}://#{USER}@localhost/#{DATABASE}?socket=#{socket}"
+        {URL => url, SOCKET => socket}.merge(env.to_h { |name| [name, url] })
+      end
+      connection = config.in_worker { |w| Connection.new(socket).tap { |mysql| w.at_stop { mysql.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 the server on +socket+;
+    # returns the last statement's result.
+    def self.run(socket, sql)
+      connection = Connection.new(socket)
+      begin
+        connection.execute(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 (STATS), so
+    # there's nothing to take away.
+    METRICS = {
+      "mysql_queries" => {kind: :counted, unit: %w[query queries], calibrate: false},
+      "mysql_rows" => {kind: :counted, unit: %w[row rows], calibrate: false},
+      "mysql_rows_examined" => {kind: :counted, unit: %w[row rows], calibrate: false},
+      "mysql_time" => {kind: :ratio, unit: "µs", floor: 300, across: false}
+    }
+
+    # What the worker's server has done so far, but for this connection
+    # (the plugin's own, reading it): the server's totals less the
+    # connection's, so nothing's left to take away. Both are as of the
+    # last statement that ended (see SETTLE).
+    STATS = <<~SQL
+      SELECT
+        CAST((SELECT VARIABLE_VALUE FROM performance_schema.global_status WHERE VARIABLE_NAME = 'Questions') -
+          (SELECT VARIABLE_VALUE FROM performance_schema.session_status WHERE VARIABLE_NAME = 'Questions') AS SIGNED),
+        CAST(server.sent - mine.sent AS SIGNED), CAST(server.examined - mine.examined AS SIGNED),
+        CAST(server.wait - mine.wait AS SIGNED)
+      FROM
+        (SELECT SUM(SUM_ROWS_SENT + SUM_ROWS_AFFECTED) sent, SUM(SUM_ROWS_EXAMINED) examined, SUM(SUM_TIMER_WAIT) wait
+          FROM performance_schema.events_statements_summary_global_by_event_name) server,
+        (SELECT SUM(SUM_ROWS_SENT + SUM_ROWS_AFFECTED) sent, SUM(SUM_ROWS_EXAMINED) examined, SUM(SUM_TIMER_WAIT) wait
+          FROM performance_schema.events_statements_summary_by_thread_by_event_name
+          WHERE THREAD_ID = PS_CURRENT_THREAD_ID()) mine
+    SQL
+
+    # Whether a client besides the reading one is running a statement.
+    # MySQL answers a statement's client before it's done with it: the
+    # statement is counted (in performance_schema) after, so a reading
+    # waits for every client to be done with what it was answered, for
+    # SETTLE seconds at most (one running a statement still is counted in
+    # the next reading instead). A client's thread shows a statement
+    # (its PROCESSLIST_COMMAND isn't Sleep) until just before it's
+    # counted, and Threads_running counts it until just after, so a
+    # reading waits while either does. Threads_running counts the
+    # server's event threads too (the event scheduler's, and each event's
+    # while it runs), which no client waits for: those are taken away.
+    # (It counts no other thread. An event's is counted a little less
+    # long than it's in performance_schema, so the two together don't
+    # miss a statement while one starts or ends.)
+    BUSY = <<~SQL
+      SELECT (SELECT COUNT(*) FROM performance_schema.threads
+          WHERE CONNECTION_TYPE IS NOT NULL AND PROCESSLIST_COMMAND != 'Sleep' AND THREAD_ID != PS_CURRENT_THREAD_ID()) +
+        ((SELECT VARIABLE_VALUE FROM performance_schema.global_status WHERE VARIABLE_NAME = 'Threads_running') -
+          (SELECT COUNT(*) FROM performance_schema.threads WHERE NAME IN ('thread/sql/event_scheduler', 'thread/sql/event_worker')) > 1)
+    SQL
+    SETTLE = 1.0
+
+    # What it has done so far by statement (its digest: a statement with
+    # ? for each constant), any connection's, for explaining a regression:
+    # of the statements run since a time (in seconds since the epoch, on
+    # the server's clock, which is the machine's), but these digests
+    # (Connection#quote'd: the plugin's own readings'). A statement's run
+    # (LAST_SEEN) is when it ended, but it's counted just after.
+    DIGESTS = <<~SQL
+      SELECT DIGEST, COUNT_STAR, SUM_ROWS_SENT + SUM_ROWS_AFFECTED, SUM_ROWS_EXAMINED, SUM_TIMER_WAIT
+      FROM performance_schema.events_statements_summary_by_digest
+      WHERE DIGEST IS NOT NULL AND UNIX_TIMESTAMP(LAST_SEEN) >= %d AND DIGEST NOT IN (%s)
+    SQL
+
+    # The digests of these statements (Connection#quote'd), and the texts
+    # of these digests.
+    DIGEST_OF = "SELECT STATEMENT_DIGEST(%s)"
+    TEXTS = "SELECT DIGEST, DIGEST_TEXT FROM performance_schema.events_statements_summary_by_digest WHERE DIGEST IN (%s)"
+
+    # What the worker's server has done so far, but for the plugin's own
+    # connection, which reads it (+connection+): [queries, rows, rows
+    # examined, time (ps)].
+    def self.totals(connection)
+      settle(connection)
+      connection.query(STATS).rows.flatten # (one row)
+    end
+
+    # Waits, SETTLE seconds at most, until the connection reading
+    # (+connection+) is the only one running a statement.
+    def self.settle(connection)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + SETTLE
+      while Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+        return if connection.query(BUSY).rows.flatten.first.zero?
+      end
+    end
+
+    # The same by measure (time in µs).
+    def self.stats(connection) = Statements.by_measure(totals(connection))
+
+    # What the server has done so far, by statement, read over
+    # +connection+: those run since +since+ (seconds since the epoch), but
+    # the +own+ digests, each one's [digest, queries, rows, rows examined,
+    # time (ps)].
+    def self.digests(connection, since, own)
+      connection.query(format(DIGESTS, since, own.map { |digest| connection.quote(digest) }.join(", "))).rows
+    end
+
+    # The digest of each of +statements+, read over +connection+.
+    def self.digests_of(connection, statements) = statements.flat_map { |sql| connection.query(format(DIGEST_OF, connection.quote(sql))).rows.flatten }
+
+    # The texts of the statements with these digests, by digest, read
+    # over +connection+.
+    def self.texts(connection, digests)
+      connection.query(format(TEXTS, digests.map { |digest| connection.quote(digest) }.join(", "))).to_h
+    end
+
+    # For benchmarks: the worker's server.
+    def self.url = ENV.fetch(URL)
+
+    # Its socket's path (for a client that takes it, not a URL).
+    def self.socket = ENV.fetch(SOCKET)
+
+    # 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::MySQL.execute")
+      run(socket, sql)
+    end
+
+    # Empties every table in its database, restarting their
+    # AUTO_INCREMENTs. For setting up, as execute is.
+    def self.reset
+      Duel.unmeasured!("Duel::MySQL.reset")
+      tables = run(socket, "SELECT table_name FROM information_schema.tables " \
+        "WHERE table_schema = DATABASE() AND table_type = 'BASE TABLE'").map(&:first)
+      # (Only this connection's: it's closed after.)
+      run(socket, "SET FOREIGN_KEY_CHECKS = 0#{tables.map { |table| "; TRUNCATE TABLE `#{table}`" }.join}")
+    end
+
+    # 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).
+    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 not read yet, as a row of MySQL.digests: it did
+      # nothing.
+      UNREAD = [nil, 0, 0, 0, 0].freeze
+
+      # A statement that did nothing yet.
+      NOTHING = [0, 0, 0, 0].freeze
+
+      # Nothing to say (no statement ran).
+      NONE = {} #: Hash[String, String]
+
+      # No statement changed.
+      UNCHANGED = [] #: Array[String]
+
+      # A reading's context: every statement's row as of it, by digest (a
+      # Hash it shares with the last reading, if none changed), the last
+      # reading's, and the digests of those that changed since.
+      Reading = Data.define(:rows, :previous, :changed)
+
+      # How long before a reading (in seconds) the next one reads the
+      # statements run since: a statement's counted just after it's run
+      # (see DIGESTS), so one counted while the reading read is read again
+      # (and the clock may be set back a little).
+      OVERLAP = 1
+
+      # A statement's numbers (or the server's, all told) by measure, time
+      # in µs.
+      def self.by_measure(numbers)
+        NAMES.each_with_index.to_h do |name, i|
+          number = numbers.fetch(i)
+          [name, (name == "mysql_time") ? number.fdiv(1_000_000) : number]
+        end
+      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 rows.)
+        @rows = {} #: Hash[String, row]
+        @since = 0 # (when the next reading reads statements run since)
+      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
+        connection = @connection.value
+        [Statements.by_measure(MySQL.totals(connection)), reading(connection)]
+      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, but its own readings': how many times each ran an
+      # iteration (+n+ of them), "an iteration: 2× SELECT `name` FROM
+      # `items` WHERE `id` = ?", and each one's share of the rest,
+      # "SELECT `name` FROM `items` WHERE `id` = ? (75%)".
+      def details(stretches, n)
+        # (A stretch whose readings share their rows: none changed.)
+        return NONE if stretches.all? { |started, stopped| stopped.context.rows.equal?(started.context.rows) }
+
+        grew = grew(stretches)
+        texts = texts(grew.keys)
+        NAMES.each_with_index.filter_map do |name, i|
+          top = grew.filter_map { |digest, more| [more.fetch(i), texts.fetch(digest, digest)] 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
+
+      # A Reading, read over +connection+: the server's statements run
+      # since (a little before) the last reading, those that changed since
+      # put in a copy of its rows.
+      def reading(connection)
+        own = @own ||= MySQL.digests_of(connection, [BUSY, STATS, format(DIGESTS, 0, "''")])
+        since = @since
+        @since = Process.clock_gettime(Process::CLOCK_REALTIME, :second) - OVERLAP
+        previous = @rows
+        rows = previous
+        changed = UNCHANGED
+        MySQL.digests(connection, since, own).each do |row|
+          digest = row.fetch(0)
+          next if row == previous[digest]
+
+          # (The last reading's Hash is its own: copied, at the first change.)
+          if rows.equal?(previous)
+            rows = previous.dup
+            changed = [] #: Array[String]
+          end
+          rows[digest] = row
+          changed << digest
+        end
+        # (None changed, again: the last Reading does. A copy is no
+        # reading's previous rows.)
+        last = @last
+        return last if last && last.previous.equal?(rows)
+
+        @rows = rows.freeze
+        @last = Reading.new(rows, previous, changed)
+      end
+
+      # What each statement did in the +stretches+, all told, by digest:
+      # those that did anything.
+      def grew(stretches)
+        grew = {} #: Hash[String, numbers]
+        stretches.each do |started, stopped|
+          before = started.context.rows
+          after = stopped.context
+          # (Read right after +started+, it says which changed since: the
+          # others can't have done anything.)
+          digests = after.previous.equal?(before) ? after.changed : after.rows.keys
+          digests.each do |digest|
+            now = after.rows.fetch(digest)
+            was = before.fetch(digest, UNREAD)
+            so_far = grew.fetch(digest, NOTHING)
+            grew[digest] = Array.new(NAMES.size) { |i| so_far.fetch(i) + now.fetch(i + 1) - was.fetch(i + 1) }
+          end
+        end
+        grew.select { |_, more| more.any?(&:positive?) }
+      end
+
+      # Each statement's text, by digest: those not yet known read from
+      # the server.
+      def texts(digests)
+        unknown = digests.reject { |digest| @texts.key?(digest) }
+        MySQL.texts(@connection.value, unknown).each { |digest, text| @texts[digest] = shorten(text) } unless unknown.empty?
+        @texts
+      end
+
+      def shorten(text) = (text.length > TEXT) ? "#{text[0, TEXT - 1]}…" : text
+    end
+
+    # A connection to a worker's server, as root, to its database.
+    class Connection
+      # Whether a server answers on +socket+.
+      def self.ping(socket)
+        new(socket).close
+      rescue Trilogy::Error
+        false
+      end
+
+      def initialize(socket)
+        # (As root: trilogy's user, unless it's given another.)
+        @client = Trilogy.new(socket: socket, database: DATABASE, multi_statement: true)
+      end
+
+      def query(sql) = @client.query(sql)
+
+      # +text+ as a string literal.
+      def quote(text) = "'#{@client.escape(text)}'"
+
+      # Runs statements; returns the last one's result.
+      def execute(sql)
+        result = query(sql)
+        result = @client.next_result while @client.more_results_exist?
+        result
+      end
+
+      # Closes it without telling the server (no QUIT, which the server
+      # could read after a benchmark's started, and count); true.
+      def close = @client.discard!
+    end
+
+    # A worker's data directory: a copy of one initialized once, with the
+    # database created in it.
+    class DataDir
+      # The server program: +server+ if it's a path, or the one by that
+      # name on +path+; nil if there's none.
+      def self.find_server(server, path = ENV.fetch("PATH", ""))
+        files = server.include?(File::SEPARATOR) ? [server] : path.split(File::PATH_SEPARATOR).map { |dir| File.join(dir, server) }
+        files.find { |file| File.executable?(file) }
+      end
+
+      # The options the server's run with, initializing +data+ or not.
+      # (They come first: mysqld takes --no-defaults only there.)
+      def self.options(data) = ["--no-defaults", "--datadir=#{data}", *OPTIONS]
+
+      def initialize(resource, server)
+        @resource = resource
+        @server = server
+      end
+
+      # Makes one in +data+: a copy of the one made for this server.
+      def create(data) = FileUtils.cp_r(@resource.cached(key) { |dir| make(dir) }, data)
+
+      private
+
+      # What a data directory is good for: this server (until it changes),
+      # and this version of the plugin.
+      def key
+        server = File.realpath(@server)
+        "mysql-#{VERSION}-#{Digest::SHA256.hexdigest([server, File.mtime(server).to_f].join("\0"))[0, 16]}"
+      end
+
+      # Initializes it (with root's password empty), and creates the
+      # database.
+      def make(data)
+        init = @resource.path("init.sql")
+        File.write(init, "CREATE DATABASE #{DATABASE};\n")
+        @resource.run(@server, *DataDir.options(data), "--initialize-insecure", "--init-file=#{init}", log: "mysqld-initialize")
+      end
+    end
+  end
+end

data/sig/duel/mysql.rbs

@@ -0,0 +1,212 @@
+module Duel
+  # A MySQL server of each worker's own, and what it did for each
+  # benchmark (mysql_queries, mysql_rows, mysql_rows_examined,
+  # mysql_time).
+  module MySQL
+    VERSION: String
+
+    URL: String
+    SOCKET: String
+    DATABASE: String
+    USER: String
+
+    # The server's options (after --no-defaults).
+    OPTIONS: Array[String]
+
+    # And once it's initialized.
+    RUNNING: Array[String]
+
+    METRICS: Hash[String, Metric::settings]
+
+    # What the worker's server has done so far, but for this connection.
+    STATS: String
+
+    # Whether a client besides the reading one is running a statement,
+    # and how long a reading waits until none is.
+    BUSY: String
+    SETTLE: Float
+
+    # What it has done so far by statement (digest), any connection's:
+    # of those run since a time, but some digests.
+    DIGESTS: String
+
+    # The digests of statements, and the texts of digests.
+    DIGEST_OF: String
+    TEXTS: String
+
+    # A statement's numbers (or the server's, all told): queries, rows,
+    # rows examined, time (ps).
+    type numbers = Array[Integer]
+
+    # A statement's row, as MySQL.digests reads it: [digest, *numbers].
+    type row = Array[untyped]
+
+    # Configures Duel for the plugin (c.use :mysql): the server (+server+
+    # the program, +args+ more of its options, +setup+ SQL each worker's
+    # database runs when it's started, +env+ the variables besides
+    # DUEL_MYSQL_URL given its URL, +scheme+ the URL's) and its metrics.
+    # Returns the plugin's own connection to it, a worker's.
+    def self.configure: (Config config, ?server: String, ?args: Array[String], ?setup: String?, ?env: Array[String],
+                         ?scheme: String) -> InWorker[Connection]
+
+    # Runs SQL on a connection of its own to the server on +socket+;
+    # returns the last statement's result.
+    def self.run: (String socket, String sql) -> ::Trilogy::Result
+
+    # What the worker's server has done so far, but for the plugin's own
+    # connection, which reads it.
+    def self.totals: (Connection connection) -> numbers
+
+    # Waits, SETTLE seconds at most, until +connection+ is the only one
+    # running a statement.
+    def self.settle: (Connection connection) -> void
+
+    # The same by measure.
+    def self.stats: (Connection connection) -> Snapshot::totals[Metric::value]
+
+    # What the server has done so far, by statement, read over
+    # +connection+: those run since +since+, but the +own+ digests, each
+    # one's [digest, *numbers].
+    def self.digests: (Connection connection, Integer since, Array[String] own) -> Array[row]
+
+    # The digest of each of +statements+, read over +connection+.
+    def self.digests_of: (Connection connection, Array[String] statements) -> Array[String]
+
+    # The texts of the statements with these digests, by digest, read over
+    # +connection+.
+    def self.texts: (Connection connection, Array[String] digests) -> Hash[String, String]
+
+    # For benchmarks: the worker's server.
+    def self.url: () -> String
+
+    # Its socket's path.
+    def self.socket: () -> 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) -> ::Trilogy::Result
+
+    # Empties every table in its database. For setting up, as execute is.
+    def self.reset: () -> ::Trilogy::Result
+
+    # 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 not read yet, as a row of MySQL.digests.
+      UNREAD: row
+
+      # A statement that did nothing yet.
+      NOTHING: numbers
+
+      # Nothing to say.
+      NONE: Hash[String, String]
+
+      # No statement changed.
+      UNCHANGED: Array[String]
+
+      # A reading's context: every statement's row as of it, by digest, the
+      # last reading's, and the digests of those that changed since.
+      class Reading
+        attr_reader rows: Hash[String, row]
+        attr_reader previous: Hash[String, row]
+        attr_reader changed: Array[String]
+
+        def initialize: (Hash[String, row] rows, Hash[String, row] previous, Array[String] changed) -> void
+      end
+
+      # How long before a reading (in seconds) the next one reads the
+      # statements run since.
+      OVERLAP: Integer
+
+      @connection: InWorker[Connection]
+      @texts: Hash[String, String]
+      @rows: Hash[String, row]
+      @last: Reading?
+      @since: Integer
+      @own: Array[String]?
+
+      # A statement's numbers (or the server's) by measure, time in µs.
+      def self.by_measure: (numbers numbers) -> Snapshot::totals[Metric::value]
+
+      # Read over +connection+, the plugin's own (a worker's).
+      def initialize: (InWorker[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, but its own readings': 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
+
+      # A Reading, read over +connection+.
+      def reading: (Connection connection) -> Reading
+
+      # What each statement did in the stretches, all told, by digest.
+      def grew: (Snapshot::stretches[Metric::value, Reading] stretches) -> Hash[String, numbers]
+
+      # Each statement's text, by digest.
+      def texts: (Array[String] digests) -> Hash[String, String]
+
+      def shorten: (String text) -> String
+    end
+
+    # A connection to a worker's server, as root, to its database.
+    class Connection
+      @client: ::Trilogy
+
+      # Whether a server answers on +socket+.
+      def self.ping: (String socket) -> bool
+
+      def initialize: (String socket) -> void
+
+      def query: (String sql) -> ::Trilogy::Result
+
+      # +text+ as a string literal.
+      def quote: (String text) -> String
+
+      # Runs statements; returns the last one's result.
+      def execute: (String sql) -> ::Trilogy::Result
+
+      # Closes it without telling the server (no QUIT); true.
+      def close: () -> bool
+    end
+
+    # A worker's data directory: a copy of one initialized once.
+    class DataDir
+      @resource: Resource
+      @server: String
+
+      # The server program: +server+ if it's a path, or the one by that
+      # name on +path+; nil if there's none.
+      def self.find_server: (String server, ?String path) -> String?
+
+      # The options the server's run with, initializing a data directory
+      # or not.
+      def self.options: (String data) -> Array[String]
+
+      def initialize: (Resource resource, String server) -> void
+
+      # Makes one in +data+: a copy of the one made for this server.
+      def create: (String data) -> void
+
+      private
+
+      def key: () -> String
+
+      def make: (String data) -> void
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: duel-mysql
+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: trilogy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+description: 'A Duel plugin: each worker gets a MySQL server of its own, and every
+  benchmark is judged on the statements it sent, the rows they read and their time
+  too.'
+email:
+- sferik@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/duel/mysql.rb
+- lib/duel/mysql/version.rb
+- sig/duel/mysql.rbs
+homepage: https://github.com/sferik/duel-ruby/tree/main/plugins/mysql
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/sferik/duel-ruby/tree/main/plugins/mysql
+  changelog_uri: https://github.com/sferik/duel-ruby/blob/main/plugins/mysql/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 MySQL server for each Duel worker, and what it did for each benchmark
+test_files: []