Docs: add CHECK constraint exclusion comparison to performance section + benchmark

The built-in way to prune on a non-key column is a data-range CHECK per
partition + constraint exclusion. Add an apples-to-apples comparison: both
prune to one partition with the same execution win; CHECK exclusion plans
~2.6x faster (~5us vs ~31us per partition), but table_range avoids the manual,
enforced (insert-blocking), rescan-on-change constraint management. Add the
measurement as section 3 of bench/benchmark.sql.

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

Author: bitner

README.md

@@ -121,6 +121,33 @@ partition count. table_range cannot match that (see
 case (scanning every partition), it still wins on total time whenever the partitions are
 sizeable.
 
+**Comparison to `CHECK` constraint exclusion.** The built-in way to prune on a non-key
+column is to put a data-range `CHECK (col BETWEEN lo AND hi)` on each partition and let the
+planner's constraint exclusion refute it. That is the most direct apples-to-apples
+baseline. Same table, 2,000 partitions, same `nk = <value>` predicate:
+
+| Same `=` predicate, 2,000 partitions | Planning | Execution | Scans |
+|---|---|---|---|
+| `CHECK` constraint exclusion (`constraint_exclusion=on`) | ~32 ms | ~0.08 ms | 1 partition |
+| table_range pruning | ~84 ms | ~0.08 ms | 1 partition |
+| no pruning | ~22 ms | ~24 ms | all 2,000 |
+
+Both are O(partitions) and give the **identical execution win**. Constraint exclusion plans
+~2.6× faster — it is C code testing an already-loaded `CHECK` expression (~5 µs/partition),
+while table_range reads each partition's index page (~31 µs/partition). What table_range
+buys for that extra planning cost is everything `CHECK` constraints make you give up:
+
+- **No manual management** — `CREATE INDEX` builds and owns the ranges; you don't compute
+  and attach a constraint per partition and keep it correct.
+- **No enforcement / no blocked inserts** — a real `CHECK` *rejects* out-of-range rows;
+  table_range's summary simply widens to cover new data, so inserts never fail.
+- **Incremental maintenance** — changing a `CHECK` means `DROP`/`ADD CONSTRAINT` with a
+  full-partition revalidation scan; table_range widens in place in `aminsert`, no rescan.
+
+So table_range offers constraint-exclusion-class pruning without manual, enforced,
+rescan-on-change constraints. Closing the ~2.6× planning gap (the per-partition index read)
+is an active optimization target.
+
 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,

bench/benchmark.sql

@@ -88,7 +88,46 @@ EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_b WHERE nk =
 DROP TABLE bench_b CASCADE;
 
 -- ====================================================================================
--- 3. (Optional) The lock-table wall. At ~10,000 partitions a non-key predicate exhausts
+-- 3. table_range vs. CHECK constraint exclusion: the built-in way to prune on a non-key
+--    column is a data-range CHECK on each partition. Same table, same predicate; we toggle
+--    constraint_exclusion vs. table_range.enable_pruning to compare the two mechanisms.
+-- ====================================================================================
+DROP TABLE IF EXISTS bench_c CASCADE;
+CREATE TABLE bench_c (region int, nk bigint) PARTITION BY LIST (region);
+-- Each partition gets a data-driven CHECK on the non-key column nk.
+SELECT format(
+  'CREATE TABLE bench_c_%s PARTITION OF bench_c FOR VALUES IN (%s); '
+  'ALTER TABLE bench_c_%s ADD CONSTRAINT bench_c_%s_nk CHECK (nk >= %s AND nk <= %s);',
+  g, g, g, g, g * 1000, g * 1000 + 999)
+FROM generate_series(1, 2000) g \gexec
+INSERT INTO bench_c
+SELECT g, g * 1000 + s FROM generate_series(1, 2000) g, generate_series(0, 49) s;
+VACUUM ANALYZE bench_c;
+CREATE INDEX bench_c_tr ON bench_c USING table_range (nk);
+
+SET constraint_exclusion = on;
+SET table_range.enable_pruning = off;
+SELECT count(*) FROM bench_c WHERE nk = 1000025;  -- warm
+\echo '==== C: CHECK constraint exclusion (table_range off) ===='
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_c WHERE nk = 1000025;
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_c WHERE nk = 1000025;
+
+SET constraint_exclusion = off;
+SET table_range.enable_pruning = on;
+SELECT count(*) FROM bench_c WHERE nk = 1000025;  -- warm
+\echo '==== C: table_range pruning (CHECK exclusion off) ===='
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_c WHERE nk = 1000025;
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_c WHERE nk = 1000025;
+
+SET constraint_exclusion = off;
+SET table_range.enable_pruning = off;
+SELECT count(*) FROM bench_c WHERE nk = 1000025;  -- warm
+\echo '==== C: no pruning (both off, scans all 2,000 partitions) ===='
+EXPLAIN (ANALYZE, COSTS OFF, TIMING OFF) SELECT count(*) FROM bench_c WHERE nk = 1000025;
+DROP TABLE bench_c CASCADE;
+
+-- ====================================================================================
+-- 4. (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".