Re: Adding comments to extension objects

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 <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Do not let urgent matters crowd out time for investment in the future.