testing.md

Testing

The test suite builds and installs the extension, starts a throwaway cluster, exercises the access method, and checks results. Each script takes a pg_config and is self-contained:

test/smoke.sh   /path/to/pg_config   # create, insert, scan, drop
test/phase2.sh  /path/to/pg_config   # compression, projection, min/max skip, filter
test/phase3.sh  /path/to/pg_config   # delete, update, MVCC, savepoints, temp tables
test/phase4.sh  /path/to/pg_config   # btree/hash indexes, constraints, conversion
test/phase5.sh  /path/to/pg_config   # custom scan, pushdown, options, vacuum
test/phase6.sh  /path/to/pg_config   # aggregate correctness and the column cache
test/audit.sh   /path/to/pg_config   # regression tests for audited defects
test/concurrency.sh      /path/to/pg_config  # concurrent same-chunk-group deletes
test/unique_conc.sh      /path/to/pg_config  # concurrent same-unique-key inserts
test/differential.sh     /path/to/pg_config  # heap-vs-columnar oracle
test/recovery.sh         /path/to/pg_config  # crash recovery and atomicity
test/fuzz.sh             /path/to/pg_config  # seeded randomized differential
test/hardening.sh        /path/to/pg_config  # corrupt-input robustness (native catalogs)
test/concurrent_diff.sh  /path/to/pg_config  # concurrent DML vs a heap oracle
test/parallel.sh         /path/to/pg_config  # parallel scan plan and results vs a heap oracle
test/sorted_projection.sh /path/to/pg_config # pgcolumnar.vacuum_sorted results and skipping
test/index_only.sh       /path/to/pg_config  # index-only scan and the visibility-map fork
test/projections.sh      /path/to/pg_config  # multiple projections and projection scan
test/arrow_export.sh     /path/to/pg_config  # Arrow IPC export read back with pyarrow
test/parquet_export.sh   /path/to/pg_config  # Parquet export read back with pyarrow and DuckDB
test/arrow_import.sh     /path/to/pg_config  # Arrow IPC import
test/parquet_import.sh   /path/to/pg_config  # Parquet import
test/arrow_nested.sh     /path/to/pg_config  # nested Arrow export
test/parquet_nested.sh   /path/to/pg_config  # nested Parquet export
test/arrow_nested_import.sh   /path/to/pg_config  # nested Arrow import
test/parquet_nested_import.sh /path/to/pg_config  # nested Parquet import
test/native_parquet_schema.sh    /path/to/pg_config  # parquet_schema type inference
test/native_read_parquet.sh      /path/to/pg_config  # read_parquet in place
test/native_parquet_fdw.sh       /path/to/pg_config  # pgcolumnar_parquet foreign tables
test/native_parquet_pushdown.sh  /path/to/pg_config  # FDW row-group predicate skipping
test/native_parquet_projection.sh /path/to/pg_config # FDW column projection pushdown
test/native_parquet_units.sh     /path/to/pg_config  # TIME/TIMESTAMP unit handling
test/native_parquet_flba.sh      /path/to/pg_config  # uuid, decimal, fixed binary reads
test/native_parquet_codecs.sh    /path/to/pg_config  # GZIP, ZSTD, LZ4_RAW page reads
test/native_parquet_hardening.sh /path/to/pg_config  # crafted-file decode guards
test/native_parquet_multifile.sh /path/to/pg_config  # directory and glob reads
test/native_parquet_streaming.sh /path/to/pg_config  # page-at-a-time reads, page guards
test/native_parquet_partition.sh /path/to/pg_config  # Hive partition columns and pruning
test/native_cancel.sh    /path/to/pg_config  # scan cancellation during a group load
test/wal_envelope.sh     /path/to/pg_config  # WAL discipline: core mechanisms only
test/decode_interrupts.sh /path/to/pg_config  # decode path stays interruptible
test/native_fetch_cache.sh /path/to/pg_config # fetch-by-row-number group cache
test/native_fetch_position.sh /path/to/pg_config # reaching a fetched row without walking
test/native_writer.sh    /path/to/pg_config  # native format catalog output
test/native_roundtrip.sh /path/to/pg_config  # native write then read round-trip
test/native_encoding.sh  /path/to/pg_config  # native per-vector encoding cascade
test/native_zonemap.sh   /path/to/pg_config  # native zone maps
test/write_minmax_fastpath.sh /path/to/pg_config # direct zone min/max comparison
test/native_skip.sh      /path/to/pg_config  # native chunk and vector skipping
test/native_agg.sh       /path/to/pg_config  # native aggregate paths
test/native_agg_deletes.sh /path/to/pg_config  # per-row-group fold when rows are deleted
test/native_bloom.sh     /path/to/pg_config  # native per-chunk bloom filters
test/native_vecskip.sh   /path/to/pg_config  # native per-vector skipping
test/native_index.sh     /path/to/pg_config  # native index and index scan
test/native_dml.sh       /path/to/pg_config  # native delete and update
test/native_ios.sh       /path/to/pg_config  # native index-only scan
test/native_projection.sh /path/to/pg_config # native projections

Defects are fixed, not documented

A limitation written into the documentation stops looking like a defect. It reads as a design choice, people plan around it, and nobody reopens it. So a defect is resolved one of two ways, and writing it down is neither:

• Fix it. Filing an issue is tracking, not resolving; an issue with no change behind it is a defect the project has decided to keep.
• Or measure it and show it is not a defect, then record the numbers so the next person does not re-litigate it. design/EXTERNAL_AUDIT_2026_07.md closes the ColumnarDeleteVectorBufferedDeleted nested scan this way: the shape is real, the cost measured linear rather than quadratic, and adding the obvious cache made it slower.

docs/limitations.md is for what is genuinely out of scope or blocked by an external constraint: an extension cannot change WAL behaviour, PostgreSQL 13 and 14 lack an API. It is not a parking space. Anything in it that is unfixed only because nobody has fixed it does not belong there.

When a fix lands, sweep the docs in the same change. ANALYZE collecting no statistics sat in limitations.md as a limitation after the implementation had already merged, which is worse than either state alone.

Differential oracle

test/differential.sh, recovery, fuzz, hardening, and concurrent_diff share test/lib.sh, a heap-versus-columnar differential oracle: a query runs against a heap mirror and the columnar table, and the results are compared as an order-independent result-set hash, so heap is the correctness oracle.

test/pbt/run.sh is a separate, PostgreSQL-independent C property test of the value-stream codecs (round-trip over randomized and boundary inputs):

test/pbt/run.sh [seed] [iterations]

Before merging: build every major

test/build_all_versions.sh

No clusters and no suites, just a compile against each installed major, about a minute for all five. Run it before merging anything that touches a version guard, a table access method callback signature, or columnar_compat.h.

The per-PR gate runs the suites on two majors, which is the right trade for test time and structurally cannot see a defect on a major it never builds. scan_analyze_next_block changed signature at PG17; a change guarded the callback at PG18 instead; PG15, PG16, PG18 and PG19 all built, and main did not compile on PG17 at all while a two-major gate reported it green. This check catches that in a minute. The full matrix remains the thorough answer.

Do not leave a branch broken on a supported major while a fix is pending. Land the fix.

The version matrix

To build and run every suite across a set of PostgreSQL majors in one pass, each in its own fresh build directory, pass their pg_config paths to the matrix helper. With no arguments it uses PostgreSQL 15 through 19:

test/run_all_versions.sh /usr/local/pg15/bin/pg_config ... /usr/local/pg19/bin/pg_config

All suites pass on PostgreSQL 15 through 19. PostgreSQL 19 is validated against 19beta2; revalidation against the final PostgreSQL 19 release is pending that release.