| 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)
| 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) |