layout: default title: Release 0.14.0

Release 0.14.0

This release hardens the 0.14.0 line around insertion locality, native partitioning, and planner-visible vector search while keeping experimental research paths out of the stable contract.

Highlights

  • PostgreSQL 16 is now part of the verified support matrix, alongside PostgreSQL 17 and 18. The release gates include PG16 installcheck and pg_upgrade 16->18.
  • clustered_pk_index accepts one or two integer key columns for directed-placement workloads. (tenant_id, id) style layouts no longer collapse placement to the first column.
  • Composite zone-map metadata tracks first-key block ranges plus a bounded second-key summary where it is safe to do so.
  • sorted_heap_zonemap_may_match_int8(regclass, bigint, bigint) provides a fail-open first-key range probe. It returns false only when valid metadata proves a range cannot match.
  • Native PostgreSQL partitioned parents have explicit sorted-heap maintenance helpers and partition-aware vector search helper paths.
  • sorted_hnsw is planner-visible through the Index AM path for covered KNN shapes, including parent Merge Append over leaf HNSW indexes.
  • GraphRAG release gates cover lifecycle, dump/restore, crash recovery, and concurrent online maintenance with KNN/GraphRAG readers.
  • sorted_heap_bulk_load_ordered(...) adds a witness-bearing ordered bulk-load helper for deterministic ingestion experiments. It is a stable helper API, not a hidden table-AM behavior change.

Stable boundaries

  • sorted_heap table storage, compaction, merge, zone-map pruning, online compact/merge, and scan stats are stable release surfaces.
  • svec/hsvec, sorted_hnsw, and the documented GraphRAG wrapper/dispatcher APIs are stable release surfaces.
  • Partition support is explicit: use the provided partition maintenance and route/helper APIs when operating on partitioned parents.
  • FlashHadamard, TurboQuant, and large-vector research sketches remain experimental. They are useful for comparison and research, but they are not part of the 0.14.0 stable contract.

Upgrade

ALTER EXTENSION pg_sorted_heap UPDATE TO '0.14.0';

The upgrade installs new SQL helpers, catalogs, and planner support functions. Existing tables do not need rewrites just to load the new extension version. Run normal maintenance or the partition helpers when you want refreshed physical order, zone-map metadata, or vector indexes after data changes.

Verification

The 0.14.0 stabilization pass was verified locally on PostgreSQL 18. The compatibility follow-up also rechecked PostgreSQL 16 and both supported upgrade paths to PostgreSQL 18:

  • make installcheck REGRESS='pg_sorted_heap sorted_hnsw graph_rag'
  • make test-release
  • make installcheck PG_CONFIG=/opt/homebrew/opt/postgresql@16/bin/pg_config REGRESS='pg_sorted_heap sorted_hnsw graph_rag'
  • PG_OLD_VERSION=16 PG_NEW_VERSION=18 ./scripts/test_pg_upgrade.sh /private/tmp 65476 65477
  • ./scripts/test_pg_upgrade.sh /private/tmp 65496 65497
  • bash ./scripts/selftest_release_archive_contract.sh /private/tmp
  • archive dry-run: git archive HEAD, then make install and make installcheck from the unpacked archive on PostgreSQL 18
  • ./scripts/bench_witness_bulk_load.sh /private/tmp 65511 8192 512 512,2048,8192 128
  • ./scripts/bench_partitioned_sorted_hnsw.sh /private/tmp 65492 3 200 6 8 5 8 16 8 32
  • bash ./scripts/bench_ann_matrix_offline_smoke.sh /private/tmp 320 3 8 3

Small smoke-benchmark observations from this pass:

  • Witness bulk-load locality improved from 15.398 average blocks per tenant for unsorted COPY to 1.320 for full/window-8192 ordering on the 8K-row smoke corpus, with similar insert time.
  • Partitioned sorted_hnsw selected/all-leaf helper paths and parent Merge Append returned 1.0000 recall on the small deterministic smoke.
  • The ANN matrix smoke emitted the expected rows for exact heap, sorted_hnsw, pgvector HNSW, IVFPQ, and FlashHadamard. The tiny offline corpus is a surface-regression smoke, not a quality benchmark.