Docs: rewrite performance/scaling sections with planning-vs-execution and native comparison

- Performance section now reports planning and execution separately (the core
  tradeoff: slower planning, much faster execution), with reproducible numbers.
- Add an honest head-to-head against native partition pruning (two identical
  columns, one the partition key, one not) showing native is hundreds of times
  cheaper to plan and effectively constant in partition count.
- New 'Scaling and partition count' section: O(n) planning, the ~10k-partition
  lock-table wall, and mitigations (max_locks_per_transaction, prepared
  statements, fewer/larger partitions, key alignment).
- Fix stale 'loaded once per plan' claim (summaries are read per partition from
  the index page, cached per plan; compare proc + constant memoized per plan).
- Replace bench/planning_benchmark.sql with bench/benchmark.sql that reproduces
  the documented tables via EXPLAIN (ANALYZE).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: bitner

README.md

@@ -80,25 +80,80 @@ EXPLAIN (COSTS OFF) SELECT * FROM places WHERE geom && ST_MakeEnvelope(0,0,10,10
 
 ## Performance
 
-The benefit is at **execution**: a selective predicate on a non-key column scans only the
-matching partition instead of every partition. On 100 partitions × 30k rows = 3M rows
-(`bench/planning_benchmark.sql`, PostgreSQL 18, warm):
-
-| | Total query time (plan + exec) |
-|---|---|
-| pruning off (scans all 100 partitions) | ~125 ms |
-| pruning on  (scans 1 partition)        | ~18 ms  |
-
-Pruning is **not** a free planning-time win: it adds a small per-plan overhead (loading
-summaries once, then evaluating each partition — single-digit to low-tens of ms on
-hundreds of partitions). It pays off when the partitions it eliminates are large enough
-that avoiding their scan outweighs that overhead — so it helps most on **large
-partitions with a selective non-key predicate**, and can be a slight net cost on tiny
-partitions. Use `table_range.enable_pruning` to measure both ways on your workload.
-
-Summaries are loaded **once per plan** (not per partition); the
-`e2e_per_plan_cache_loads_once_regardless_of_partitions` test asserts exactly one
-catalog load for a 64-partition query.
+The deal is simple and worth stating plainly: **table_range trades more planning time for
+much less execution time.** A selective predicate on a non-key column scans only the
+matching partition instead of every partition, which is a huge execution win — but the
+planner pays to evaluate each partition's summary, so planning gets slower.
+
+The numbers below are reproducible with `bench/benchmark.sql` (`cargo pgrx run pg18`, then
+`\i bench/benchmark.sql`); they report `EXPLAIN (ANALYZE)` planning and execution time
+separately, warm.
+
+**Faster execution.** 300 partitions × 8,000 rows (2.4M rows), `WHERE nk = <value in one
+partition>`, PostgreSQL 18, warm:
+
+| | Planning | Execution | Total |
+|---|---|---|---|
+| pruning **off** (scans all 300 partitions) | ~3 ms | ~100 ms | ~103 ms |
+| pruning **on** (scans 1 partition) | ~12 ms | ~0.4 ms | **~12 ms** |
+
+Planning is ~4× slower, execution is ~230× faster, and total time drops ~8×. The win
+grows with how much data the eliminated partitions hold, and shrinks as partitions get
+smaller — on tiny partitions the planning overhead can exceed the execution it saves, so
+measure your workload with `table_range.enable_pruning`.
+
+**Honest comparison to native pruning.** When a predicate is on the *partition key*,
+PostgreSQL prunes natively — and that path is in a different league, because it eliminates
+partitions from a sorted bound array *before* they are ever locked or opened. The table
+below uses two identical columns on the same table: `pk` (the range partition key, pruned
+natively) and `nk` (the same values, not the key, pruned by table_range):
+
+| Same `=` predicate, 2,000 partitions | Planning | Execution |
+|---|---|---|
+| native pruning — column **is** the partition key | **~0.1 ms** | ~0.02 ms |
+| table_range — column is **not** the partition key | ~80 ms | ~0.06 ms |
+| no pruning — scans all 2,000 partitions | ~30 ms | ~26 ms |
+
+Native pruning is *hundreds of times* cheaper to plan and is effectively constant in the
+partition count. table_range cannot match that (see
+[Scaling](#scaling-and-partition-count)): its job is the case native pruning **can't** do
+— eliminating partitions by a non-key column. Against the realistic alternative for that
+case (scanning every partition), it still wins on total time whenever the partitions are
+sizeable.
+
+Each partition's summary is read from its own index page and cached for the duration of
+one plan; the per-column compare function and the query constant are resolved once per
+plan and reused across partitions (so the per-partition cost is a typed min/max compare,
+not repeated catalog lookups).
+
+## Scaling and partition count
+
+table_range's planning cost is **O(number of partitions)**: PostgreSQL builds a planner
+node for every partition of the table for a non-key predicate, and table_range evaluates
+each one's summary. This is fundamentally different from native partition pruning, which
+is ~O(log n) because it prunes on the partition key before expansion. There is no public
+planner hook that prunes a non-key column before expansion, so this O(n) cost is inherent.
+
+Two practical consequences and how to handle them:
+
+- **Lock table exhaustion (a hard wall, ~10k partitions on defaults).** Any query touching
+  a non-key column must lock *every* partition (and its indexes) while planning. With the
+  default `max_locks_per_transaction = 64`, a query over ~10,000 partitions fails with
+  `ERROR: out of shared memory` / `You might need to increase "max_locks_per_transaction"`.
+  This is a PostgreSQL limit on wide non-key scans, not specific to this extension (native
+  key pruning avoids it by never locking pruned partitions). **Mitigation:** raise
+  `max_locks_per_transaction` (e.g. to a few thousand) and restart — it preallocates
+  shared memory for the lock table, pushing the wall out in proportion.
+- **Planning time grows with partition count.** Even below the lock wall, planning scales
+  linearly. **Mitigations:** prefer **fewer, larger partitions** (table_range's sweet spot
+  — the execution win is biggest there anyway); use **prepared statements** so a plan is
+  reused across executions and the planning cost is amortized; and where you can,
+  **align the hot filter column with the partition key** so native pruning handles it.
+
+In short, table_range targets **hundreds to a few thousand sizeable partitions with a
+selective non-key predicate**. For tens of thousands of partitions, non-key pruning is not
+something an extension can make sub-linear today; that would require pre-expansion pruning
+support in PostgreSQL core.
 
 ## Supported predicates
 
@@ -154,8 +209,19 @@ range-type tests, which exercise the same code path.
 
 ## Limitations
 
+- **Planning is O(partitions)** for non-key predicates, with a hard lock-table wall around
+  ~10k partitions on default settings. See [Scaling](#scaling-and-partition-count) for the
+  cause and mitigations (`max_locks_per_transaction`, prepared statements, fewer/larger
+  partitions). Native partition-key pruning does not have this limit; table_range is for
+  the cases native pruning cannot handle.
+- Pruning is a **planning-time cost / execution-time win** tradeoff: on small partitions
+  the per-plan overhead can exceed the scan it saves. Measure with
+  `table_range.enable_pruning`.
 - `NOT IN` / `<> ALL`, `NOT (...)`, expression predicates, and parameterized
   prepared-statement plans are kept rather than pruned.
 - Inserts keep summaries current incrementally, but deletes only relax them (the summary
   can stay wider than the live data until a `VACUUM`/`REINDEX` re-tightens it) — always
   correct, just potentially less selective.
+- Pruning engages only while the index is **valid** (`indisvalid`); the planner ignores
+  invalid indexes, so anything that invalidates a table_range index silently disables its
+  pruning until rebuilt.

bench/benchmark.sql

@@ -0,0 +1,97 @@
+-- Reproducible benchmarks for pg_table_range.
+--
+--   cargo pgrx run pg18
+--   \i bench/benchmark.sql
+--
+-- Reports planning and execution time separately (warm) via EXPLAIN (ANALYZE), for:
+--   1. Plan-vs-execution tradeoff: a selective non-key predicate, pruning on vs. off.
+--   2. Honest comparison to native partition pruning: two identical columns, one the
+--      partition key (pruned natively) and one not (pruned by table_range).
+--
+-- Note: cargo pgrx run reuses its database. If you have previously loaded older versions
+-- of this extension, stale event triggers can interfere; this script drops the extension
+-- and recreates it for a clean baseline.
+
+\set ECHO none
+\pset pager off
+
+DROP EXTENSION IF EXISTS pg_table_range CASCADE;
+-- Clear any event triggers left behind by older builds (no-ops on a clean DB).
+DROP EVENT TRIGGER IF EXISTS table_range_hide_indexes_trg;
+DROP EVENT TRIGGER IF EXISTS table_range_drop_trg;
+DROP EVENT TRIGGER IF EXISTS table_range_opclass_sync_trg;
+DROP FUNCTION IF EXISTS table_range_hide_indexes() CASCADE;
+CREATE EXTENSION pg_table_range;
+
+-- ====================================================================================
+-- 1. Plan-vs-execution tradeoff: 300 partitions x 8,000 rows, predicate hits 1 partition.
+--    `region` is the partition key; `val` is a disjoint band per partition (non-key).
+-- ====================================================================================
+DROP TABLE IF EXISTS bench_a CASCADE;
+CREATE TABLE bench_a (region int, val bigint, pad text) PARTITION BY LIST (region);
+SELECT format('CREATE TABLE bench_a_%s PARTITION OF bench_a FOR VALUES IN (%s);', g, g)
+FROM generate_series(1, 300) g \gexec
+INSERT INTO bench_a
+SELECT g, g * 1000000 + s, repeat('x', 40)
+FROM generate_series(1, 300) g, generate_series(0, 7999) s;
+VACUUM ANALYZE bench_a;
+CREATE INDEX bench_a_tr ON bench_a USING table_range (val);
+
+SET table_range.enable_pruning = on;
+SELECT count(*) FROM bench_a WHERE val = 150004000;  -- warm
+\echo '==== A: pruning ON (scans 1 of 300 partitions) ===='
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_a WHERE val = 150004000;
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_a WHERE val = 150004000;
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_a WHERE val = 150004000;
+
+SET table_range.enable_pruning = off;
+SELECT count(*) FROM bench_a WHERE val = 150004000;  -- warm
+\echo '==== A: pruning OFF (scans all 300 partitions) ===='
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_a WHERE val = 150004000;
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_a WHERE val = 150004000;
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_a WHERE val = 150004000;
+DROP TABLE bench_a CASCADE;
+
+-- ====================================================================================
+-- 2. table_range vs. native pruning: 2,000 partitions, two identical columns.
+--    `pk` is the RANGE partition key (native pruning); `nk` holds the same values but is
+--    NOT the key (table_range pruning). Same `=` predicate, so the only difference is
+--    which mechanism prunes.
+-- ====================================================================================
+DROP TABLE IF EXISTS bench_b CASCADE;
+CREATE TABLE bench_b (pk bigint, nk bigint) PARTITION BY RANGE (pk);
+SELECT format('CREATE TABLE bench_b_%s PARTITION OF bench_b FOR VALUES FROM (%s) TO (%s);',
+              g, g * 1000, (g + 1) * 1000)
+FROM generate_series(1, 2000) g \gexec
+INSERT INTO bench_b
+SELECT v, v FROM (SELECT g * 1000 + s AS v
+                  FROM generate_series(1, 2000) g, generate_series(0, 49) s) q;
+VACUUM ANALYZE bench_b;
+CREATE INDEX bench_b_tr ON bench_b USING table_range (nk);
+
+SET table_range.enable_pruning = off;
+SELECT count(*) FROM bench_b WHERE pk = 1000500;  -- warm
+\echo '==== B: NATIVE pruning (predicate on the partition key) ===='
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_b WHERE pk = 1000500;
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_b WHERE pk = 1000500;
+
+SET table_range.enable_pruning = on;
+SELECT count(*) FROM bench_b WHERE nk = 1000500;  -- warm
+\echo '==== B: table_range pruning (same predicate, non-key column) ===='
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_b WHERE nk = 1000500;
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_b WHERE nk = 1000500;
+
+SET table_range.enable_pruning = off;
+SELECT count(*) FROM bench_b WHERE nk = 1000500;  -- warm
+\echo '==== B: NO pruning (non-key column, scans all 2,000 partitions) ===='
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_b WHERE nk = 1000500;
+DROP TABLE bench_b CASCADE;
+
+-- ====================================================================================
+-- 3. (Optional) The lock-table wall. At ~10,000 partitions a non-key predicate exhausts
+--    the lock table on default settings:
+--      ERROR: out of shared memory
+--      HINT:  You might need to increase "max_locks_per_transaction".
+--    Raise max_locks_per_transaction (e.g. to 4000) and restart to push the wall out.
+--    Native key pruning is unaffected because it never locks pruned partitions.
+-- ====================================================================================