Add ids to catalog/view columns in documentation

From: "Tristan Partin" <tristan(at)partin(dot)io>
To: "pgsql-hackers" <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: Add ids to catalog/view columns in documentation
Date: 2026-11-18 18:34:24
Message-ID: DMYJX1CMUDNX.247IXDBT1TZVV@partin.io
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

When referring to columns within catalog/views, I found it annoying that
they were not linkable. You could only link to something higher level
and then the reader was left to scroll and search for the column
definition.

I think adding IDs to column definitions would be a good idea. In this
initial patch, I've only decided to change pg_stat_statements
documentation. It should make it easier to view necessary changes and
visualize the impact of this change within the documentation.

Things that have changed:

- Octothorope is now visible when hovering a column within the column
definitions of pg_stat_statements and pg_stat_statements_info views
- Copying that link and pasting it in a new tab will take you directly
to the row of the column definition with a background color change to
highlight what was linked to. I understand that the CSS we use in-tree
is not the same CSS that is used on postgresql.org. I could make
a similar CSS change there as well if this seems like a good
direction.

I think there is discussion to be had about ID names. For instance,
I used the format <view>-view.<column>. Should we do that for all views?
How should IDs for catalog columns look? For pg_stat_statements
specifically, should I have used an ID like
pgstatstatements-<view>.<column>? Maybe there isn't a one size fits all
solution.

I'm happy to extend this to the rest of the documented catalogs/views if
this seems like a good idea to others. Question for a committer: would
you like the patch series for everything to look a certain way?

In the future, we could extend this concept to functions and operators
like in https://www.postgresql.org/docs/current/functions-json.html for
example.

--
Tristan Partin
PostgreSQL Contributors Team
AWS (https://aws.amazon.com)

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message João Rito 2026-11-18 18:40:32 Re: [PATCH v2] Avoid carrying self lock-only xmax to updated tuple
Previous Message Greg Burd 2026-11-18 18:24:59 Re: Hash index: stop registering pin-only bucket pages in WAL (remove REGBUF_NO_CHANGE)