On Sat, Aug 8, 2026 at 06:12:40PM -0400, Andrew Dunstan wrote:
> I also asked claude for a template. It gave me one with a worked example. It's
> attached.
I asked Claude Code to check our built-in extensions and got a useful
report. Seems like we have some work to do.
---------------------------------------------------------------------------
● I scanned the local PostgreSQL master checkout at
/usr/local/src/gen/pgsql/postgresql (REL_19_BETA1-587-gb5978350222, 20devel),
checking every *.control extension's install and upgrade
scripts for COMMENT ON.
Answer: almost none of them. Only 13 of the 54 contrib extensions use COMMENT
ON at all — the other 41 create their objects with no comments.
The 41 contrib extensions with zero COMMENT ON
amcheck, btree_gin, btree_gist, citext, dblink, earthdistance, file_fdw,
fuzzystrmatch, hstore, hstore_plperl, hstore_plperlu, intagg, lo, ltree,
ltree_plpython3u, pageinspect,
pg_buffercache, pg_freespacemap, pg_logicalinspect, pg_prewarm, pgrowlocks,
pg_stash_advice, pg_stat_statements, pgstattuple, pg_surgery, pg_trgm,
pg_visibility, pg_walinspect, pgcrypto,
postgres_fdw, autoinc, insert_username, moddatetime, sslinfo, tablefunc, tcn,
tsm_system_rows, tsm_system_time, unaccent, uuid-ossp, xml2
The 13 that do use it
┌─────────────────────────────────────────────────────────────────────────────────────────────┬──────────────────┬───────────────────────────────────┐
│ Extension
│ COMMENT ON count │ What's commented │
├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────────────────────────────┤
│ seg
│ 15 │ operators/functions │
├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────────────────────────────┤
│ cube
│ 11 │ operators/functions │
├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────────────────────────────┤
│ isn
│ 8 │ functions │
├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────────────────────────────┤
│ intarray
│ 7 │ operators/functions │
├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────────────────────────────┤
│ bloom
│ 1 │ COMMENT ON ACCESS METHOD │
├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────────────────────────────┤
│ dict_int
│ 1 │ COMMENT ON TEXT SEARCH DICTIONARY │
├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────────────────────────────┤
│ dict_xsyn
│ 1 │ COMMENT ON TEXT SEARCH DICTIONARY │
├─────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────────────────────────────┤
│ bool_plperl, bool_plperlu, jsonb_plperl, jsonb_plperlu, jsonb_plpython3u,
hstore_plpython3u │ 1 each │ COMMENT ON TRANSFORM │
└─────────────────────────────────────────────────────────────────────────────────────────────┴──────────────────┴───────────────────────────────────┘
---------------------------------------------------------------------------
and check externally-developed extensions:
---------------------------------------------------------------------------
● I sampled 31 widely-used external extensions by downloading their current
sources from GitHub and scanning their install/upgrade scripts (excluding test
and regression directories).
The distribution is more polarized than contrib: most external extensions
also skip COMMENT ON entirely, but the ones that do use it tend to use it
exhaustively rather than on a handful of
objects.
No COMMENT ON at all (19 of 31)
hypopg, pgaudit, pg_hint_plan, pg_ivm, pgjwt, pgmq, pg_partman, pg_qualstats,
pg_repack, pgroonga, pgsql-http, pg_stat_kcache, pg_stat_monitor, pgTAP,
pg_tle, pguint, postgresql-hll, rum,
zombodb
Notably pgTAP — ~1,000 assertion functions across sql/pgtap.sql.in, not one
of them commented.
Systematic users (4)
┌───────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Extension │ Scale
│
├───────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Citus │ 470 of 543 UDF definition files carry a COMMENT ON —
essentially every function it creates │
├───────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ orafce │ 255 in the current install script alone (orafce--4.16.sql), all
COMMENT ON FUNCTION │
├───────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ pgRouting │ 332 statements across 162 function files; the comments are
multi-line, embedding parameter lists and doc URLs │
├───────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ pgvector │ 149 in vector--0.8.6.sql — verified against the copy installed
on this host │
└───────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Token users (7)
Apache AGE (10), pgsodium (10), pg_cron (9), pg_dirtyread (5), topn (5),
pg_graphql (4), and TimescaleDB (2) — which is the minimal case:
sql/comment_apache.sql and sql/comment_tsl.sql each
contain a single COMMENT ON EXTENSION timescaledb, and nothing on the objects
themselves.
PostGIS is the interesting case
Its extension script contains no COMMENT ON for its own objects — the 21 hits
I found are inside the bodies of CreateTopology() and UpgradeTopology(),
commenting columns of user topology
tables at runtime.
But PostGIS does ship comments, just outside the extension mechanism.
doc/Makefile.in generates postgis_comments.sql, raster_comments.sql,
topology_comments.sql, and sfcgal_comments.sql from
the DocBook XML via XSLT (doc/xsl/*_comments.sql.xsl) — a COMMENT ON for
every documented function, derived from the documentation itself. Those are
installed by a separate make
comments-install target and applied by hand; extensions/postgis/Makefile.in
never references them, so CREATE EXTENSION postgis does not add them. It's the
only project in the sample that
treats comments as a build artifact of the docs rather than hand-written SQL.
Caveats on method
Counts span all versioned scripts in each repo, not just the current install
script, so some reflect comments added in one upgrade path. pg_graphql builds
its SQL through pgrx/Rust, so
anything emitted from Rust macros rather than sql/*.sql wouldn't be caught.
And this is a 31-extension sample of a much longer tail — it establishes the
pattern, not a census.
--
Bruce Momjian <[email protected]> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.
