Thread

psql: display of object comments

Josh Kupershmidt <schmiddy@gmail.com> — 2011-07-09T17:16:37Z

Hi all,

I would like to fix psql's incomplete and inconsistent handling of
object comments. I think this subject can be handled separately from
the pg_comments discussion, and we can focus on the
appearance/behavior of psql commands here.

First, As brought up recently [1], comments for the following object
types are not currently displayed by any psql backslash command:

  CAST
  CONSTRAINT
  CONVERSION
  FOREIGN DATA WRAPPER
  PROCEDURAL LANGUAGE
  SERVER

In the case of PROCEDURAL LANGUAGE, it was mere oversight that \dL did
not display comments, and I'm not aware of any reason why we're not
doing so for the other objects above. I'd like to propose adding an
additional column to the respective psql backslash commands for the
above object types which will display any comment associated with the
object.

Second, comments of the following object types would IMO be better
displayed in the object's individual backslash command, and not in \dd
as they are now:

  DOMAIN

Third, comments for the following objects are displayed by both \dd
and the object's individual backslash command:

  AGGREGATE
  FOREIGN TABLE (via \d+)
  INDEX
  FUNCTION
  OPERATOR
  SEQUENCE
  TABLE
  VIEW

Seems like there's no need to add more noise to \dd for these cases.

Fourth, there is a bug in at least the display of comments for indexes
using \d+ (the "Description" is empty when it shouldn't be).

As a summary, here is how I am proposing we display object comments [2]:

1.) Object comments displayed by \dd:

 CONSTRAINT
 OPERATOR CLASS
 OPERATOR FAMILY
 RULE
 TRIGGER

2.) Object comments displayed in the backslash commands for the object:

 AGGREGATE                     \da
 CAST                          \dC+
 COLLATION                     \dO
 COLUMN                        \d+ tablename
 CONVERSION                    \dc
 DATABASE                      \l+
 DOMAIN                        \dD and \dT+
 EXTENSION                     \dx
 FOREIGN DATA WRAPPER          \dew
 FOREIGN TABLE                 \det and \d+
 FUNCTION                      \df+
 INDEX                         \di+ and \d+
 LARGE OBJECT                  \dl
 OPERATOR                      \do
 PROCEDURAL LANGUAGE           \dL
 ROLE                          \dg+
 SCHEMA                        \dn+
 SEQUENCE                      \ds+ and \d+
 SERVER                        \des
 TABLE                         \dt+ and \d+
 TABLESPACE                    \db+
 TYPE                          \dT
 TEXT SEARCH CONFIGURATION     \dF
 TEXT SEARCH DICTIONARY        \dFd
 TEXT SEARCH PARSER            \dFp
 TEXT SEARCH TEMPLATE          \dFt
 VIEW                          \dv+

A few notes:
 a.) As you can see, there's not much consistency in whether we
display object comments only in verbose mode or not. I'm open to
suggestions on how to tweak/standardize this.
 b.) I'd rather not have any overlap between groups 1.) and 2.).
 c.) \dd doesn't yet display all the object types it should (operator
class & family are missing); that's slated to be fixed with the
pg_comments patch though.

Patch attached and comments welcome; will add to next CF barring
objections. I've also attached a test .sql file I was using to make up
a bunch of comments, it might save you some time if you're interested
in trying the patch out.

--
[1] http://archives.postgresql.org/pgsql-hackers/2011-05/msg00991.php
[2] The object types broken down here should cover all comment-able
types on http://www.postgresql.org/docs/9.1/static/sql-comment.html