Correct the performance story; the index overhead was a measurement artifact

While investigating the "per-partition index planning overhead," controlled
same-session A/B measurements showed my earlier numbers were confounded by
relcache warmth and cross-session machine load:

- The index-validity effect on planning is ~3 ms on 500 partitions (warm), not the
  ~85 ms I previously reported. So the invalid-index event trigger I added is not
  worth its cost (a confusing INVALID display) and is reverted, along with the
  ineffective get_relation_info_hook.
- The real, clean benefit is at EXECUTION: on 100 partitions x 30k rows (3M rows,
  warm), a selective non-key predicate runs in ~18 ms with pruning vs ~125 ms
  without (~7x). Pruning adds a small per-plan overhead and can be a slight net cost
  on tiny partitions; it wins when eliminated partitions are large.
- Rewrote bench/planning_benchmark.sql to measure total (plan+exec) time, warm, on
  realistic partition sizes, and rewrote the README performance section to match.
- Gated the test-only cache-load diagnostics so production builds are warning-free.

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

Author: bitner

README.md

@@ -78,21 +78,23 @@ EXPLAIN (COSTS OFF) SELECT * FROM places WHERE geom && ST_MakeEnvelope(0,0,10,10
 
 ## Performance
 
-The win is at **planning time** on wide trees, where the planner would otherwise build
-paths for every partition. On a 1000-partition table queried by a non-key column
-(`bench/planning_benchmark.sql`, PostgreSQL 18):
-
-| | Planning time | Result |
-|---|---|---|
-| pruning off | ~210 ms | 50 rows |
-| pruning on  | ~100 ms | 50 rows |
-
-Pruning removes ~110 ms of child-path planning here. Note the absolute numbers are higher
-than they could be: because summaries are owned by a real index, PostgreSQL loads index
-metadata for every partition during planning (a flat overhead, ~85 ms on this bare
-1000-partition table — proportionally smaller when partitions already carry indexes).
-
-Summaries themselves are loaded **once per plan** (not per partition); the
+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.
 

bench/planning_benchmark.sql

@@ -1,49 +1,51 @@
--- Planning-time benchmark for table_range pruning.
+-- Benchmark for table_range pruning.
 --
--- Builds a wide partition tree where the queried column is NOT the partition key, so
--- native PostgreSQL pruning cannot help, and compares planning time + plan size with
--- table_range pruning off vs. on. Run with:
+-- Measures end-to-end query time (planning + execution, warm) for a selective predicate
+-- on a NON-partition-key column, with table_range pruning on vs. off. Native PostgreSQL
+-- cannot prune on a non-key column, so without pruning the query scans every partition.
 --
 --   cargo pgrx run pg18
 --   \i bench/planning_benchmark.sql
 --
--- Look at the "Planning Time" line and the number of child plans in each EXPLAIN.
+-- Pruning trades a small per-plan overhead (loading summaries + evaluating each
+-- partition) for skipping the scan of non-matching partitions, so it wins when the
+-- partitions it eliminates are large enough to outweigh that overhead.
 
-\set part_count 1000
+\set part_count 100
+\set rows_per_part 30000
 
 DROP TABLE IF EXISTS bench_events CASCADE;
-CREATE TABLE bench_events (region int, val bigint) PARTITION BY LIST (region);
+CREATE TABLE bench_events (region int, val bigint, pad text) PARTITION BY LIST (region);
 
--- One partition per region; each holds a disjoint 1000-wide band of `val`.
 SELECT format(
-    'CREATE TABLE bench_events_%s PARTITION OF bench_events FOR VALUES IN (%s);',
-    g, g
-)
+    'CREATE TABLE bench_events_%s PARTITION OF bench_events FOR VALUES IN (%s);', g, g)
 FROM generate_series(1, :part_count) g \gexec
 
+-- region is the partition key; val is a disjoint band per partition (the queried,
+-- non-key column).
 INSERT INTO bench_events
-SELECT g, (g * 1000) + s
-FROM generate_series(1, :part_count) g,
-     generate_series(0, 49) s;
-
-ANALYZE bench_events;
+SELECT g, g * 1000000 + s, repeat('x', 50)
+FROM generate_series(1, :part_count) g, generate_series(0, :rows_per_part - 1) s;
 
+VACUUM ANALYZE bench_events;
 CREATE INDEX bench_events_tr ON bench_events USING table_range (val);
 
-\echo '==================== pruning OFF ===================='
-SET table_range.enable_pruning = off;
-EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF, SUMMARY ON)
-SELECT * FROM bench_events WHERE val BETWEEN 500000 AND 500049;
+\timing on
 
-\echo '==================== pruning ON  ===================='
+-- Warm the relation cache first so the numbers reflect steady state, not first-touch
+-- partition-metadata loading (which both modes pay equally).
 SET table_range.enable_pruning = on;
-EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF, SUMMARY ON)
-SELECT * FROM bench_events WHERE val BETWEEN 500000 AND 500049;
+SELECT count(*) FROM bench_events WHERE val = 50000000;
+
+\echo '==================== pruning ON (warm) ===================='
+SELECT count(*) FROM bench_events WHERE val = 50000000;
+SELECT count(*) FROM bench_events WHERE val = 50000000;
 
-\echo '==================== correctness check (must match) ===================='
 SET table_range.enable_pruning = off;
-SELECT count(*) AS off_count FROM bench_events WHERE val BETWEEN 500000 AND 500049;
-SET table_range.enable_pruning = on;
-SELECT count(*) AS on_count FROM bench_events WHERE val BETWEEN 500000 AND 500049;
+SELECT count(*) FROM bench_events WHERE val = 50000000;
+
+\echo '==================== pruning OFF (warm) ===================='
+SELECT count(*) FROM bench_events WHERE val = 50000000;
+SELECT count(*) FROM bench_events WHERE val = 50000000;
 
 DROP TABLE bench_events CASCADE;

src/prune_hook.rs

@@ -11,10 +11,12 @@ use crate::{TABLE_RANGE_ENABLE_PRUNING, TABLE_RANGE_LOG_PRUNING_DEBUG};
 /// One load per top-level plan (regardless of partition count) proves the per-plan cache.
 static CACHE_LOADS: AtomicU64 = AtomicU64::new(0);
 
+#[cfg(any(test, feature = "pg_test"))]
 pub fn cache_load_count() -> u64 {
     CACHE_LOADS.load(Ordering::Relaxed)
 }
 
+#[cfg(any(test, feature = "pg_test"))]
 pub fn reset_cache_load_count() {
     CACHE_LOADS.store(0, Ordering::Relaxed);
 }