documentation on comment
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/18/sql-altertable.html
Description:
after spending some time searching for how to do comments, maybe some
documentation could be made clearer:
links from 'create table', 'alter table' to
https://www.postgresql.org/docs/current/sql-comment.html (maybe in the 'see
also' section).
and in 'comment' part, mention that comments on columns can be seen with \d+
and comments on tables with \dt+ (\dv+ on views)
so from 'Comments can be viewed using psql's \d family of commands.' to
something like 'Comments can be viewed using psql's \d family of commands.
To see comments on columns, use \d+ table_name command, for comment on the
table itself, use \dt+ table_name command'.
thanks for wonderful work on documentation
Michal
On Wednesday, October 7, 2026, PG Doc comments form <noreply@postgresql.org>
wrote:
and in 'comment' part, mention that comments on columns can be seen with
\d+
and comments on tables with \dt+ (\dv+ on views)
so from 'Comments can be viewed using psql's \d family of commands.' to
something like 'Comments can be viewed using psql's \d family of commands.
To see comments on columns, use \d+ table_name command, for comment on the
table itself, use \dt+ table_name command'.
The comment SQL page shouldn’t go and try to document how the \d commands
behave. The psql page should do that. If something is lacking fix it
there and maybe fix the pointer here to that new section.
David J.
On Wed, 2026-10-07 at 11:23 +0000, PG Doc comments form wrote:
Page: https://www.postgresql.org/docs/18/sql-altertable.html
after spending some time searching for how to do comments, maybe some
documentation could be made clearer:links from 'create table', 'alter table' to
https://www.postgresql.org/docs/current/sql-comment.html (maybe in the 'see
also' section).and in 'comment' part, mention that comments on columns can be seen with \d+
and comments on tables with \dt+ (\dv+ on views)
so from 'Comments can be viewed using psql's \d family of commands.' to
something like 'Comments can be viewed using psql's \d family of commands.
To see comments on columns, use \d+ table_name command, for comment on the
table itself, use \dt+ table_name command'.
Cross references are a good thing. But we should be careful not to repeat
everything everywhere. I pretended to be clueless and both looked in
the index (where the COMMENT command is referenced) and used the search
for "table comment", which also took me right to the COMMENT command.
So that is pretty straightforward to find.
As you mention, that page points you to psql's \d commands.
Searching for "comment" on that page, I quickly found the \dd metacommand
(TIL!), which shown comments on some types of objects. Also, it points
you to the \d commands for the respective object types to see comments on
those. There I quickly found that \d<whatever>+ will show the description.
So I think that it is easy enough to find the information.
On the other hand, there is always room for improvement. You suggest to
specifically mention \d+ and \dt+ in the COMMENT documentation. I can
understand that wish, since it were comments on those objects that you
were looking for. But it feels undesirable to me to only mention some
object types and not the others. How would you feel about something like
Comments can be viewed using psql's \d family of commands, in particular
\dd and the + suffix for the \d commands.
Yours,
Laurenz Albe