v2.2.0

Evidence honesty, plus result verification that is both cheaper and stronger.

Breaking

• POST /api/v1/queries/explain/compare renames the cost row and changes its format.
  Total cost … −26.9× is now Planner cost (estimate) … −96.3%. Planner cost is an
  abstract quantity in scaled page-fetch units — not proportional to elapsed time, and not
  reliably comparable across two plans — so rendering it as a fold change beside an
  execution-time row implied a speedup the number cannot support. Anything parsing that
  row's evidence string, or expecting × in its change, needs updating.

Added

• timing_runs (1–5) on compare. Above 1, each side runs that many times under ANALYZE
  and the row reports the median with the observed range — 28ms (5 runs, 26ms–40ms).
  Median rather than mean, so a single cold or contended run cannot drag the figure to a
  number no execution actually produced.
• Noise detection. When the run-to-run spread is at least as large as the gap between
  medians, the result is reported as inside the measurement noise rather than as a speedup.
• caveat on comparison metrics, rendered beside the number and carried into exported
  reports.
• EXPLAIN (SETTINGS) on every plan. Non-default planner configuration changes both
  the plan chosen and every cost shown, so a comparison is only meaningful when both sides
  were produced under the same settings.

Changed

• Result verification is roughly twice as cheap and no longer capped. It previously ran
  four executions and, past 1000 rows, sorted the entire result to sample it. It is now one
  aggregate pass per side — count + sum + bit_xor over a per-row hash — with no sort
  and three scalars on the wire. All three aggregates are commutative, so row order cannot
  affect the answer. VerifiedEqual now means every row was compared, at any result
  size.
• Execution time is labelled as the single sample it is when timing_runs is 1.
• The demo seeds 300k rows instead of 8000, so the before/after difference is larger
  than the timing noise. Seeding takes about two seconds.

Fixed

• The "no rewrite offered" message omitted a supported pattern and overstated another; it
  now lists them accurately and explains that declining is the normal outcome.
• Release signature verification requires cosign v3 or newer — v2 cannot read Sigstore
  v0.3 bundles and fails in a way that resembles a bad signature.

Install

docker pull ghcr.io/pgquery-narrative/pgquerynarrative:2.2.0

Binaries for linux and darwin on amd64 and arm64 are attached, with checksums.txt, an
SBOM, and a .cosign.bundle for each. Upgrading from 2.0.x requires running migrations
first — the schema gate is version 56.

Full changelog: https://github.com/pgquery-narrative/pgquerynarrative/blob/main/CHANGELOG.md