Adding comments to extension objects

On 2026-08-08 Sa 9:17 AM, Bruce Momjian wrote:

I think SQL object comments are very useful for users, and even more
useful now that many people are using MCP:

https://momjian.us/main/blogs/pgblog/2026.html#March_16_2026

Would someone please volunteer to check all externally-developed
extensions to see if they have the appropriate object comments, and if
not, either create a patch to add them or contact the author suggesting
they add them. I have done this already for pgvector:

https://momjian.us/main/blogs/pgblog/2026.html#March_16_2026

I think we need to be more specific about what might help here. I asked
Claude what sort of objects commenting on in this way would help. Here's
its answer:

*Always worth it: *|TABLE|, |FOREIGN TABLE|, partitioned tables,
|COLUMN|, |VIEW|, |MATERIALIZED VIEW| Why: Read by essentially every
server; named directly in every query

*Worth it if your server reads them*|: SCHEMA|, |FUNCTION|/|PROCEDURE|,
|TYPE|, |DOMAIN|, |SERVER| Why: Read by better servers, and the model
can name all of them

*Usually not worth it: *|INDEX|, |CONSTRAINT|, |TRIGGER|, |POLICY|,
|SEQUENCE|, |OPERATOR|, |RULE|, |ROLE|, |DATABASE|, |TABLESPACE| Why:
Rarely fetched, and mostly not nameable in generated SQL

So, if your extension creates a Foreign Data Wrapper, as several of mine
do, there's really nothing for you to do. By all means comment on it,
but it is very unlikely to help an MCP server. On the other hand, if it
creates functions and types, commenting on those is probably a good
idea, and if it creates tables it's a very good idea.

I also asked claude for a template. It gave me one with a worked
example. It's attached.

cheers

andrew

--
Andrew Dunstan
EDB:https://www.enterprisedb.com

On Sat, Aug 8, 2026 at 06:12:40PM -0400, Andrew Dunstan wrote:

So, if your extension creates a Foreign Data Wrapper, as several of mine do,
there's really nothing for you to do. By all means comment on it, but it is
very unlikely to help an MCP server. On the other hand, if it creates functions
and types, commenting on those is probably a good idea, and if it creates
tables it's a very good idea.

I also asked claude for a template. It gave me one with a worked example. It's
attached.

Great idea to use Claude. Also, we should consider cases where it will
help users but not necessarily MCP. FYI, pgvector already completed my
request:

https://github.com/pgvector/pgvector/issues/1013

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

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

Sometimes I wish there were something like Python's docstrings where
you can get more detailed usage instructions interactively.

So something like comments, but more detailed.

It could be exposed as CALL HELP(<the object name>) returning whatever
is there in the system.

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@momjian.us> https://momjian.us
EDB https://enterprisedb.com

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