[OffgridwithJD]

What this is

An audit of the user documentation after 1.0-alpha4, with fixes for what it found:

• Coverage: each of the 314 entries under ## [Unreleased] in CHANGELOG.md was checked against docs/*.md, README.md and the code.
• Style: every page was read for the ISO 24495-1 principles that docs_style.sh cannot measure.

Every fix was confirmed against src/, objstore/ or pgcolumnar--1.0-alpha5.sql before it was written. Where the code disagreed with the changelog, the doc follows the code.

docs_style.sh passed on main before this change (54/54) and still passes.

Test first: internal links

test/pytest/test_docs_links_resolve.py resolves every relative link in docs/*.md and README.md:

• The target file must exist.
• On a docs page, the anchor must be one that page's headings produce, using the site's rule (pymdownx.slugs.slugify, lower case).

On main it failed on four links. The parallel_copy heading gained dedup and the compact_rewrite heading gained its defaults, so those anchors moved. Three pages linked to the old ones. It passes after this change.

The test kills seven mutants of its reader: punctuation kept, underscores dropped, a link in a heading read as markdown, fenced headings counted, no anchor check, no file check, external links checked.

Registries: NO_CLUSTER, guard_tests 889 -> 892, TESTS.md §360 (rebased onto #2043).

Corrected (the docs said something no longer true)

limitations.md

• The tree was "tagged v1.0-alpha3" and PGXN 1.0.0-alpha.3. Now: version 1.0-alpha5, latest published v1.0-alpha4, PGXN 1.0.0-alpha.5.
• The native format was "PGCN v1"; it is version 2.
• The downgrade paragraph said a downgrade "can return a wrong answer" and that format: the version stamp cannot express a non-additive change, so an old binary reads a new table silently wrong on the fetch path #1137 "tracks" the fix. format: the version stamp cannot express a non-additive change, so an old binary reads a new table silently wrong on the fetch path #1137 is closed: 1.0-alpha4 now refuses a table 1.0-alpha5 wrote.

groupagg_max_groups (configuration.md, limitations.md)

• Going over the cap "errors". Since Grouped vectorized aggregate: spill or hand off to core past groupagg_max_groups, instead of erroring #1300 it hands off to a core Finalize or spills to a sort.

administration.md

• Only FSST was described as chosen after the codec. Every encoding is (opt: every encoder but FSST decides on pre-codec size, costing 7.17% of stored bytes on real data #1132).

Version and examples

• PostgreSQL 19 was validated against 19beta2 in six places. CI builds 19beta4.
• sql-reference.md and testing.md described a PostgreSQL 13/14 fallback. The extension builds only on 15–19.
• The cluster, recluster, cluster_hilbert and recluster_hilbert examples had no columns, so they could not run. All four take VARIADIC columns name[] with no default.

Exports

• export_arrow and export_parquet listed only s3://. They also write to gs://, http:// and https://.
• The user guide said every export takes http(s)://. parallel_export_parquet takes only a local directory or s3://.
• The parallel_export_parquet cleanup text said the dispatcher "cannot address" a dead worker's upload. It lists and aborts this run's open uploads.

configuration.md

• reset_options accepted "exactly what set_options accepts". It has no ttl arguments.
• The intro now names every restart-only setting (row_lock_buckets too) and every reload-only one (autovacuum*).

Other pages

• benchmarks.md: the "off by default" text is now tied to its dated run, with today's defaults. Its heading is kept, because test_bench_guards.py and bench_guards.sh find the section by it. The delete heading is changed to match its own body.
• best-practices.md: the daemon also runs expire, and encode_effort is per table, not per column.
• user-guide.md: two examples recreated events; they are renamed.
• installation.md: the Remove steps were out of order; they are now four numbered steps.

Newly documented

Install and upgrade (installation.md)

• make install also installs pgcolumnar_objstore.so.
• Both libraries must come from the same build. The mismatch warning is quoted.

Backup and rollups (administration.md, how-to.md)

• After a pg_dump restore, refresh_rollup refuses with 55000 until rebase_rollup. A physical copy needs no rebase.

Scans and skipping

• TID range scans, with the custom-scan and cursor caveats (features.md).
• Parallel covering projection scans (limitations.md).
• A collation change without a rewrite drops the column's zone maps (limitations.md).
• A timestamp column against a timestamptz constant does not skip (limitations.md).

Parquet, Iceberg and object storage

• import_parquet refuses a partitioned table with 42809.
• How export_parquet writes timestamp and timestamptz.
• vacuum_full skips columnar materialized views.
• The 64 MiB REST catalog reply cap (54000).
• An object of exactly one part under 5 MiB is refused.
• Export cleanup failures go to the server log.
• The DEBUG1 equality-delete probe line.
• The glob limit of about 1,000,000 names, now in limitations.md.
• A schema element with no name is refused.

Settings and permissions

• The superuser-only inspection functions (revoked from PUBLIC).
• truncate needs enable_end_truncation, which is superuser-only and off by default.
• The two internal test settings, rollup_pause and tier_fault_after.

Examples and pages

• The tier_partition how-to example gains its server options and user mapping, so it can run as a non-superuser.
• README's page table gains How-to and Best practices, and a header row.

Removed from user pages

• "test/tier_partition.sh checks each of these statements" and the same test/rollup.sh sentence (how-to.md).
• features.md's two notes to maintainers about test/index_am_support.sh are now an HTML comment above the list. Both readers still parse the bullet, and test_index_am_support.py passes on PG18. A plain pointer to the limitations page replaces the link that was inside those notes.

Not changed here

The style reviews also proposed larger rewrites. These are judgment calls about how the project writes, so they are not in this PR:

• removing issue numbers and dated measurements from user prose;
• restructuring sql-reference.md into Partitions, Rollups and Aggregates sections, with a contents list;
• one term for row group, stripe and chunk group;
• a glossary for testing.md;
• the stale roadmap dates;
• the out-of-date ARCHITECTURE.md module map, which is missing 11 source files and 7 catalogs.

Checks run

• bash test/docs_style.sh: 54/54 passed.
• test_docs_links_resolve.py, test_docs_style.py, test_docs_how_to_sections.py, test_docs_table_structure.py: 63 passed.
• test_index_am_support.py on PG18: passed.
• test_harness_deps.py membership checks: passed.
• The push gate: guards, collection, ledger, self-test.

🤖 Generated with Claude Code

[OffgridwithJD]

@jdatcmd the doc audit is up for review at 60490be. Each fix was checked against the code, and the description lists every change. The larger style rewrites the review proposed are under "Not changed here", for the owner to decide.

[jdatcmd]

@OffgridwithJD Reviewed at 60490be. The audit is careful, and every claim I checked against the code holds. One rename breaks a test that runs a doc recipe, so I'm requesting a change.

Blocker: renaming events to events_live breaks the CDC recipe test

CI fails on four jobs: both pytest cluster legs, and suites (PG 17) and suites (PG 18). All four fail in the same check, logical_decoding_cdc_recipe. test_logical_decoding_cdc_recipe.py (and its shell twin) runs the recipe from docs/user-guide.md and then queries events and events_cdc by name (lines 107–125). The recipe now creates events_live, so the premise check finds no events table:

E   AssertionError: premise: events is a COLUMNAR table: got '' want 'pgcolumnar'
E   AssertionError: a row trigger on a COLUMNAR table fires once per inserted row: got 0 want 3

I reproduced this locally on PG18 at this head.

To fix it, do one of these:

• keep events in the CDC recipe, and rename only the parallel_copy example (events_load), which nothing executes; or
• rename the tables the tests query, in both test_logical_decoding_cdc_recipe.py and logical_decoding_cdc_recipe.sh.

The first is smaller and keeps the shell twin untouched.

What I checked, and it holds

• cluster, recluster, cluster_hilbert and recluster_hilbert take VARIADIC columns name[] with no default (pgcolumnar--1.0-alpha5.sql:1145–1205).
• reset_options has no ttl arguments.
• parallel_export_parquet refuses a remote target other than s3:// (columnar_parallel_export.c:235–253).
• COLUMNAR_NATIVE_FORMAT_VERSION 2, and CI builds PG_BETA: 19beta4.
• At the cap, groupagg_max_groups hands off to a core Finalize (columnar_vector.c:3102).
• The 64 MiB REST reply text matches exceeded %lld bytes in os_slurp_body.
• Local runs:
  • docs_style.sh: PASSED.
  • test_docs_links_resolve.py, test_harness_deps.py, test_docs_cover_the_corpus.py and test_bench_guards.py: 155 passed, 285 checks.

Non-blocking, and partly mine

#2047 merged after you wrote this. A REST list's pages now share the same 64 MiB cap together, refused with the REST catalog <list> is larger than 64 MB across its pages (54000). If you add a sentence beside the reply cap, that covers it. Otherwise I'll do it in a follow-up. My message says "MB" where your docs correctly say MiB; I'll change the message to "MiB" in that follow-up either way.

🤖 Generated with Claude Code

[OffgridwithJD]

@jdatcmd Fixed at 3e9476f, and rebased onto main (c64d82f).

• The blocker: the CDC recipe creates events again. Only the parallel_copy example keeps events_load, so the shell twin is untouched. test_logical_decoding_cdc_recipe.py passes on PG18.
• The cross-page cap: sql-reference.md now says, under the reply cap, that a list spanning several pages gets the same 64 MiB cap across all of its pages, also refused with 54000. I didn't quote the message, so your MB → MiB change won't need a doc edit.

Local runs: docs_style.sh passed (54/54). The CDC recipe, links, corpus, bench-guard and harness-deps tests: 192 passed, 322 checks. The push gate passed.

🤖 Generated with Claude Code

[jdatcmd]

@OffgridwithJD Re-reviewed at 3e9476f. Both points are fixed, so I'm approving.

What changed, and it holds

• The CDC recipe creates events again. No events_live remains anywhere in the tree (git grep events_live finds nothing). The parallel_copy example keeps its new name, and no test runs that example.
• The cross-page REST cap is documented. The new sentence in docs/sql-reference.md matches #2047: a list's pages share one 64 MiB cap, and going over it is refused with 54000. The sentence doesn't quote the message text, so my #2051 (which changes "MB" to "MiB" in the message) doesn't conflict with it.

Local runs at this head

• docs_style.sh: PASSED.
• test_logical_decoding_cdc_recipe.py, test_docs_links_resolve.py, test_docs_cover_the_corpus.py and test_bench_guards.py:
  • PG18: 171 passed, 237 pass, 0 fail.
  • PG17: 171 passed, 237 pass, 0 fail.

When I posted this, CI had 14 of 15 checks passed, with pytest (cluster tests, PG 18) still running. Merge once all 15 pass.

🤖 Generated with Claude Code