Обсуждение: Show comments in \dRp+, \dRs+, and \dX+ psql meta-commands
Hi,
The psql meta-commands that list publications, subscriptions, and extended
statistics (\dRp+, \dRs+, and \dX+) do not display their associated comments,
whereas other \d meta-commands do. This makes it inconvenient to view
these objects together with their descriptions.
I'd like to propose the attached patch to improve \dRp+ and \dRs+ so
they include comments for publications and subscriptions. The patch also
extends the \dX meta-command to accept the + option, allowing comments
for extended statistics to be shown when requested. Thoughts?
BTW, while working on this, I also noticed that \dRs+ currently outputs nearly
all subscription parameter settings (for example, [1]), whereas other
\d meta-commands tend to show only a subset of details. So, as new parameters
(or columns in pg_subscription) are added, the number of columns in \dRs+
will continue to grow, which could make the output harder to use.
I think it might be better to exclude parameter settings to keep
the output manageable.
As just idea, it may be sufficient for \dRs+ to display commonly used
identifying information such as Conninfo and Description in addition to
the fields shown by \dRs (Name, Owner, Enabled, and Publication).
Other details (e.g., Failover) could still be viewed directly in
pg_subscription.
Thought?
Regards,
[1]
\dRs+
List of subscriptions
Name | Owner | Enabled | Publication |
Binary | Streaming | Two-phase commit | Disable on error | Origin |
Password required | Run as owner? | Failover | Retain dead tuples |
Max retention duration | Retention active | Synchronous commit |
Conninfo | Skip LSN | Description
-----------------+---------------------------+---------+-------------+--------+-----------+------------------+------------------+--------+-------------------+---------------+----------+--------------------+------------------------+------------------+--------------------+-----------------------------+------------+-------------------
regress_testsub | regress_subscription_user | f | {testpub} |
f | parallel | d | f | any | t
| f | f | f |
0 | f | off |
dbname=regress_doesnotexist | 0/00000000 | test subscription
(1 row)
--
Fujii Masao
Вложения
Hi Fujii,
Due to recent changes in describe.c and subscription.out, v1 was no
longer applying. I rebased it just to test the feature -- feel free to
revert it.
v2 attached.
On 16/02/2026 15:57, Fujii Masao wrote:
> The psql meta-commands that list publications, subscriptions, and extended
> statistics (\dRp+, \dRs+, and \dX+) do not display their associated comments,
> whereas other \d meta-commands do. This makes it inconvenient to view
> these objects together with their descriptions.
>
> I'd like to propose the attached patch to improve \dRp+ and \dRs+ so
> they include comments for publications and subscriptions. The patch also
> extends the \dX meta-command to accept the + option, allowing comments
> for extended statistics to be shown when requested. Thoughts?
The feature LGTM!
Here some tests:
postgres=# \pset null '(null)'
Null display is "(null)".
## Statistics
CREATE TABLE t (a int, b int);
CREATE STATISTICS stat1 (dependencies) ON a, b FROM t;
COMMENT ON STATISTICS stat1 IS 'stat 🐘 comment';
CREATE STATISTICS stat2 (dependencies) ON b, a FROM t;
COMMENT ON STATISTICS stat2 IS NULL;
postgres=# \dX+
List of extended statistics
-[ RECORD 1 ]+----------------
Schema | public
Name | stat1
Definition | a, b FROM t
Ndistinct | (null)
Dependencies | defined
MCV | (null)
Description | stat 🐘 comment
-[ RECORD 2 ]+----------------
Schema | public
Name | stat2
Definition | a, b FROM t
Ndistinct | (null)
Dependencies | defined
MCV | (null)
Description | (null)
## Publications
CREATE PUBLICATION pub FOR TABLE t;
COMMENT ON PUBLICATION pub IS E'pub \n comment';
postgres=# \dRp+
Publication pub
-[ RECORD 1 ]-----+---------
Owner | jim
All tables | f
All sequences | f
Inserts | t
Updates | t
Deletes | t
Truncates | t
Generated columns | none
Via root | f
Description | pub +
| comment
Tables:
"public.t"
## Subscriptions
CREATE SUBSCRIPTION sub
CONNECTION 'dbname=postgres'
PUBLICATION pub
WITH (connect = false);
COMMENT ON SUBSCRIPTION sub IS E'sub \"\'comment';
postgres=# \dRs+
List of subscriptions
-[ RECORD 1 ]----------+----------------
Name | sub
Owner | jim
Enabled | f
Publication | {pub}
Binary | f
Streaming | parallel
Two-phase commit | d
Disable on error | f
Origin | any
Password required | t
Run as owner? | f
Failover | f
Retain dead tuples | f
Max retention duration | 0
Retention active | f
Synchronous commit | off
Conninfo | dbname=postgres
Receiver timeout | -1
Skip LSN | 0/00000000
Description | sub "'comment
The comments are displayed as expected.
One unrelated thing caught my attention though: NULLs and empty strings
are both displayed as NULL, which is expected according to
CreateComments() in comment.c
...
/* Reduce empty-string to NULL case */
if (comment != NULL && strlen(comment) == 0)
comment = NULL;
...
However, I couldn't find anything in the docs that clearly says that
it's going to be the case -- at least not in comment.sgml.
CREATE SEQUENCE s1;
COMMENT ON SEQUENCE s1 IS '';
CREATE SEQUENCE s2;
COMMENT ON SEQUENCE s2 IS NULL;
postgres=# \ds+
List of sequences
-[ RECORD 1 ]-----------
Schema | public
Name | s1
Type | sequence
Owner | jim
Persistence | permanent
Size | 8192 bytes
Description | (null)
-[ RECORD 2 ]-----------
Schema | public
Name | s2
Type | sequence
Owner | jim
Persistence | permanent
Size | 8192 bytes
Description | (null)
Is it perhaps an undocumented behaviour?
Best, Jim
Вложения
Hi, On 16/02/26 11:57, Fujii Masao wrote: > Hi, > > The psql meta-commands that list publications, subscriptions, and extended > statistics (\dRp+, \dRs+, and \dX+) do not display their associated comments, > whereas other \d meta-commands do. This makes it inconvenient to view > these objects together with their descriptions. > > I'd like to propose the attached patch to improve \dRp+ and \dRs+ so > they include comments for publications and subscriptions. The patch also > extends the \dX meta-command to accept the + option, allowing comments > for extended statistics to be shown when requested. Thoughts? > Thanks for working on this. I miss the \dX+ feature when reviewing your other path on improving documentation for CREATE TABLE LIKE. The code seems correct to me and it's working as described, I don't any special comments. > BTW, while working on this, I also noticed that \dRs+ currently outputs nearly > all subscription parameter settings (for example, [1]), whereas other > \d meta-commands tend to show only a subset of details. So, as new parameters > (or columns in pg_subscription) are added, the number of columns in \dRs+ > will continue to grow, which could make the output harder to use. > I think it might be better to exclude parameter settings to keep > the output manageable. > > As just idea, it may be sufficient for \dRs+ to display commonly used > identifying information such as Conninfo and Description in addition to > the fields shown by \dRs (Name, Owner, Enabled, and Publication). > Other details (e.g., Failover) could still be viewed directly in > pg_subscription. > Thought? > Yeah, I agree that the output can will be harder to read when the number of parameters (or columns) in pg_subscription grow, but since most of these columns are visible only on verbose mode (+) it doesn't seems an issue IMHO. In the future if the output columns grow too much we can rethink this, but for now I think that it's fine. +1 for the patch. (I've reviewed the v2 attached by Jim on [1]) [1] https://www.postgresql.org/message-id/82b25785-0dc1-46d6-93ac-ce385a3a0bfc%40uni-muenster.de -- Matheus Alcantara EDB: https://www.enterprisedb.com
On 2026-Feb-16, Fujii Masao wrote: > The psql meta-commands that list publications, subscriptions, and extended > statistics (\dRp+, \dRs+, and \dX+) do not display their associated comments, > whereas other \d meta-commands do. This makes it inconvenient to view > these objects together with their descriptions. I'm not in love with the fact that some "plus" commands display the description and I wish I had a way to turn that off. On the other hand, sometimes I want to see the comments for objects and little else. But I think it's infrequent that I want to see both the comments and simultaneously the details that only appear in verbose mode. This is to say that I'm also not in love with expanding the "plus" commands to print comments in more cases as you propose, and I wonder if we can find something more ergonomical. For instance, what if we added a second flag to the commands (eg. an asterisk/star, but could be anything that's easily typed), so that you can invoke the normal "verbose" bit separately from the comments? So if you want details but no comments, you use "\d+", and if you want comments but no details you use "\d*", and if you want everything, then you use \d+* or \d*+? -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "I dream about dreams about dreams", sang the nightingale under the pale moon (Sandman)
On Fri, Feb 20, 2026 at 6:29 PM Jim Jones <jim.jones@uni-muenster.de> wrote: > > Hi Fujii, > > Due to recent changes in describe.c and subscription.out, v1 was no > longer applying. I rebased it just to test the feature -- feel free to > revert it. > > v2 attached. Thanks for reviewing and rebasing the patch! I noticed that I forgot to update the psql help message for \dX+, so I've revised the patch. Attached is v3. > One unrelated thing caught my attention though: NULLs and empty strings > are both displayed as NULL, which is expected according to > CreateComments() in comment.c > > ... > /* Reduce empty-string to NULL case */ > if (comment != NULL && strlen(comment) == 0) > comment = NULL; > ... > > However, I couldn't find anything in the docs that clearly says that > it's going to be the case -- at least not in comment.sgml. > > CREATE SEQUENCE s1; > COMMENT ON SEQUENCE s1 IS ''; > CREATE SEQUENCE s2; > COMMENT ON SEQUENCE s2 IS NULL; > > postgres=# \ds+ > List of sequences > -[ RECORD 1 ]----------- > Schema | public > Name | s1 > Type | sequence > Owner | jim > Persistence | permanent > Size | 8192 bytes > Description | (null) > -[ RECORD 2 ]----------- > Schema | public > Name | s2 > Type | sequence > Owner | jim > Persistence | permanent > Size | 8192 bytes > Description | (null) > > Is it perhaps an undocumented behaviour? I'm not sure why this behavior isn't documented, but it seems worth addressing in a separate documentation patch. Regards, -- Fujii Masao
Вложения
On 20.02.2026 18:48, Álvaro Herrera wrote: > So if you want details but > no comments, you use "\d+", and if you want comments but no details you > use "\d*", and if you want everything, then you use \d+* or \d*+? We need to keep in mind two more modifiers: S for system objects and x for eXtended mode. So it may be looks like slightly awkward: \dSx+* Another option is to use psql variable (for example ECHO_COMMENTS on/off) to force comments in \d* commands. I'm not sure what option is better. But I like the idea of printing comments. -- Pavel Luzanov Postgres Professional: https://postgrespro.com
> On Feb 26, 2026, at 11:32, Fujii Masao <masao.fujii@gmail.com> wrote: > > >> One unrelated thing caught my attention though: NULLs and empty strings >> are both displayed as NULL, which is expected according to >> CreateComments() in comment.c >> >> ... >> /* Reduce empty-string to NULL case */ >> if (comment != NULL && strlen(comment) == 0) >> comment = NULL; >> ... >> >> However, I couldn't find anything in the docs that clearly says that >> it's going to be the case -- at least not in comment.sgml. >> >> CREATE SEQUENCE s1; >> COMMENT ON SEQUENCE s1 IS ''; >> CREATE SEQUENCE s2; >> COMMENT ON SEQUENCE s2 IS NULL; >> >> postgres=# \ds+ >> List of sequences >> -[ RECORD 1 ]----------- >> Schema | public >> Name | s1 >> Type | sequence >> Owner | jim >> Persistence | permanent >> Size | 8192 bytes >> Description | (null) >> -[ RECORD 2 ]----------- >> Schema | public >> Name | s2 >> Type | sequence >> Owner | jim >> Persistence | permanent >> Size | 8192 bytes >> Description | (null) >> >> Is it perhaps an undocumented behaviour? > > I'm not sure why this behavior isn't documented, but it seems worth > addressing in a separate documentation patch. > Actually, I am right about to post a doc patch for that. I noticed that while reviewing the other patch about comment beforethe holiday vacation. My patch will be out today or tomorrow. Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
> On Feb 26, 2026, at 11:32, Fujii Masao <masao.fujii@gmail.com> wrote: > > On Fri, Feb 20, 2026 at 6:29 PM Jim Jones <jim.jones@uni-muenster.de> wrote: >> >> Hi Fujii, >> >> Due to recent changes in describe.c and subscription.out, v1 was no >> longer applying. I rebased it just to test the feature -- feel free to >> revert it. >> >> v2 attached. > > Thanks for reviewing and rebasing the patch! > > I noticed that I forgot to update the psql help message for \dX+, > so I've revised the patch. Attached is v3. > >> One unrelated thing caught my attention though: NULLs and empty strings >> are both displayed as NULL, which is expected according to >> CreateComments() in comment.c >> >> ... >> /* Reduce empty-string to NULL case */ >> if (comment != NULL && strlen(comment) == 0) >> comment = NULL; >> ... >> >> However, I couldn't find anything in the docs that clearly says that >> it's going to be the case -- at least not in comment.sgml. >> >> CREATE SEQUENCE s1; >> COMMENT ON SEQUENCE s1 IS ''; >> CREATE SEQUENCE s2; >> COMMENT ON SEQUENCE s2 IS NULL; >> >> postgres=# \ds+ >> List of sequences >> -[ RECORD 1 ]----------- >> Schema | public >> Name | s1 >> Type | sequence >> Owner | jim >> Persistence | permanent >> Size | 8192 bytes >> Description | (null) >> -[ RECORD 2 ]----------- >> Schema | public >> Name | s2 >> Type | sequence >> Owner | jim >> Persistence | permanent >> Size | 8192 bytes >> Description | (null) >> >> Is it perhaps an undocumented behaviour? > > I'm not sure why this behavior isn't documented, but it seems worth > addressing in a separate documentation patch. > > Regards, > > -- > Fujii Masao > <v3-0001-psql-Show-comments-in-dRp-dRs-and-dX-psql-meta-co.patch> I applied v3 locally, built it and played a little bit, then reviewed the code change. Everything looks good to me. Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
> On Feb 26, 2026, at 13:07, Chao Li <li.evan.chao@gmail.com> wrote: > > > >> On Feb 26, 2026, at 11:32, Fujii Masao <masao.fujii@gmail.com> wrote: >> >> >>> One unrelated thing caught my attention though: NULLs and empty strings >>> are both displayed as NULL, which is expected according to >>> CreateComments() in comment.c >>> >>> ... >>> /* Reduce empty-string to NULL case */ >>> if (comment != NULL && strlen(comment) == 0) >>> comment = NULL; >>> ... >>> >>> However, I couldn't find anything in the docs that clearly says that >>> it's going to be the case -- at least not in comment.sgml. >>> >>> CREATE SEQUENCE s1; >>> COMMENT ON SEQUENCE s1 IS ''; >>> CREATE SEQUENCE s2; >>> COMMENT ON SEQUENCE s2 IS NULL; >>> >>> postgres=# \ds+ >>> List of sequences >>> -[ RECORD 1 ]----------- >>> Schema | public >>> Name | s1 >>> Type | sequence >>> Owner | jim >>> Persistence | permanent >>> Size | 8192 bytes >>> Description | (null) >>> -[ RECORD 2 ]----------- >>> Schema | public >>> Name | s2 >>> Type | sequence >>> Owner | jim >>> Persistence | permanent >>> Size | 8192 bytes >>> Description | (null) >>> >>> Is it perhaps an undocumented behaviour? >> >> I'm not sure why this behavior isn't documented, but it seems worth >> addressing in a separate documentation patch. >> > > Actually, I am right about to post a doc patch for that. I noticed that while reviewing the other patch about comment beforethe holiday vacation. My patch will be out today or tomorrow. > > Best regards, > -- > Chao Li (Evan) > HighGo Software Co., Ltd. > https://www.highgo.com/ > Hi Fujii-san, This is the tiny patch to enhance the doc of COMMON ON command. Would you please take a look? Thanks a lot. https://www.postgresql.org/message-id/26476097-B1C1-4BA8-AA92-0AD0B8EC7190%40gmail.com Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
On 26/02/2026 04:32, Fujii Masao wrote:
> I'm not sure why this behavior isn't documented, but it seems worth
> addressing in a separate documentation patch.
Yeah, it also surprised me a bit. Having a NULL instead of '' in \d* is
IMO not that dramatic, but things get different when accessing the
catalog directly, e.g.
postgres=# \pset null '(null)'
postgres=# CREATE TABLE t (id int);
CREATE TABLE
postgres=# COMMENT ON TABLE t IS '';
COMMENT
postgres=# SELECT obj_description('t'::regclass, 'pg_class');
obj_description
-----------------
(null)
(1 row)
Best, Jim
On 26/02/2026 06:34, Chao Li wrote: > I applied v3 locally, built it and played a little bit, then reviewed the code change. Everything looks good to me. Same here, v3 LGTM. My previous tests worked as expected and the help entry is now also correct. $ psql postgres -c "\?" | grep "\dX" \dX[x+] [PATTERN] list extended statistics Thanks! Best, Jim
On Thu, Feb 26, 2026 at 1:57 PM Pavel Luzanov <p.luzanov@postgrespro.ru> wrote: > > On 20.02.2026 18:48, Álvaro Herrera wrote: > > So if you want details but > > no comments, you use "\d+", and if you want comments but no details you > > use "\d*", and if you want everything, then you use \d+* or \d*+? > > We need to keep in mind two more modifiers: S for system objects and x > for eXtended mode. > So it may be looks like slightly awkward: \dSx+* > > Another option is to use psql variable (for example ECHO_COMMENTS > on/off) to force comments in \d* commands. Or both? IOW, display comments if either that psql variable is enabled or "*" is specified in the \d command; otherwise, omit them. With this approach, users who prefer the current behavior (showing comments with the "+" option) can simply enable that psql variable and see comments without adding "*". Conversely, users who prefer not to include comments can disable that variable and use "*" only when they want to display them. Regards, -- Fujii Masao
On 2026-Feb-26, Fujii Masao wrote: > Or both? IOW, display comments if either that psql variable is enabled > or "*" is specified in the \d command; otherwise, omit them. > > With this approach, users who prefer the current behavior (showing comments > with the "+" option) can simply enable that psql variable and see comments > without adding "*". Conversely, users who prefer not to include comments > can disable that variable and use "*" only when they want to display them. I like this, thanks. I wonder though if the variable ought to be more generic. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "Always assume the user will do much worse than the stupidest thing you can imagine." (Julien PUYDT)
On Thu, Feb 26, 2026 at 10:53 PM Álvaro Herrera <alvherre@kurilemu.de> wrote: > > On 2026-Feb-26, Fujii Masao wrote: > > > Or both? IOW, display comments if either that psql variable is enabled > > or "*" is specified in the \d command; otherwise, omit them. > > > > With this approach, users who prefer the current behavior (showing comments > > with the "+" option) can simply enable that psql variable and see comments > > without adding "*". Conversely, users who prefer not to include comments > > can disable that variable and use "*" only when they want to display them. > > I like this, thanks. I wonder though if the variable ought to be more > generic. I'm fine with this direction, but I think it should be handled as a separate improvement to the \d meta-commands, rather than as part of the current patch extending \dRp+, \dRs+, and \dX+. I'm thinking to first commit the v3 patch so that comments on publications, subscriptions, and extended statistics can be viewed via \d. After that, we can consider a broader overhaul of the \d commands and how comments are displayed, as discussed. Regards, -- Fujii Masao
> On Feb 27, 2026, at 07:09, Fujii Masao <masao.fujii@gmail.com> wrote: > > On Thu, Feb 26, 2026 at 10:53 PM Álvaro Herrera <alvherre@kurilemu.de> wrote: >> >> On 2026-Feb-26, Fujii Masao wrote: >> >>> Or both? IOW, display comments if either that psql variable is enabled >>> or "*" is specified in the \d command; otherwise, omit them. >>> >>> With this approach, users who prefer the current behavior (showing comments >>> with the "+" option) can simply enable that psql variable and see comments >>> without adding "*". Conversely, users who prefer not to include comments >>> can disable that variable and use "*" only when they want to display them. >> >> I like this, thanks. I wonder though if the variable ought to be more >> generic. > > I'm fine with this direction, but I think it should be handled as a separate > improvement to the \d meta-commands, rather than as part of the current patch > extending \dRp+, \dRs+, and \dX+. > > I'm thinking to first commit the v3 patch so that comments on publications, > subscriptions, and extended statistics can be viewed via \d. After that, > we can consider a broader overhaul of the \d commands and how comments are > displayed, as discussed. > To me, that sounds reasonable. Best regards, — Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
On 2026-Feb-27, Fujii Masao wrote: > I'm fine with this direction, but I think it should be handled as a separate > improvement to the \d meta-commands, rather than as part of the current patch > extending \dRp+, \dRs+, and \dX+. > I'm thinking to first commit the v3 patch so that comments on publications, > subscriptions, and extended statistics can be viewed via \d. After that, > we can consider a broader overhaul of the \d commands and how comments are > displayed, as discussed. No objection to that. Do you intend to work on that yourself, or should we seek volunteers? -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
On 26.02.2026 16:53, Álvaro Herrera wrote: > I wonder though if the variable ought to be more > generic. Can you please explain what you mean by more generic? On 27.02.2026 11:27, Álvaro Herrera wrote: > On 2026-Feb-27, Fujii Masao wrote: >> I'm thinking to first commit the v3 patch so that comments on publications, >> subscriptions, and extended statistics can be viewed via \d. After that, >> we can consider a broader overhaul of the \d commands and how comments are >> displayed, as discussed. > No objection to that. > > Do you intend to work on that yourself, or should we seek volunteers? > If no one volunteers, I can try in next release cycle for v20. -- Pavel Luzanov Postgres Professional: https://postgrespro.com
On Fri, Feb 27, 2026 at 7:04 PM Pavel Luzanov <p.luzanov@postgrespro.ru> wrote: > > On 26.02.2026 16:53, Álvaro Herrera wrote: > > I wonder though if the variable ought to be more > > generic. > > Can you please explain what you mean by more generic? > > > On 27.02.2026 11:27, Álvaro Herrera wrote: > > On 2026-Feb-27, Fujii Masao wrote: > >> I'm thinking to first commit the v3 patch so that comments on publications, > >> subscriptions, and extended statistics can be viewed via \d. After that, > >> we can consider a broader overhaul of the \d commands and how comments are > >> displayed, as discussed. > > No objection to that. > > > > Do you intend to work on that yourself, or should we seek volunteers? > > > > If no one volunteers, I can try in next release cycle for v20. Yeah, please feel free to work on it! That would be much appreciated! Regards, -- Fujii Masao
On 2026-Feb-27, Pavel Luzanov wrote: > On 26.02.2026 16:53, Álvaro Herrera wrote: > > I wonder though if the variable ought to be more > > generic. > > Can you please explain what you mean by more generic? I think if we limit it to "does plus add comments or not" is a bit too narrow a definition. Maybe "BACKSLASH_CMD_OPTS" that takes a comma-separated list, say \pset BACKSLASH_CMD_OPTS comments,expanded and with that then all commands behave as if the '*' and 'x' options had been given. -- Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/ "If you want to have good ideas, you must have many ideas. Most of them will be wrong, and what you have to learn is which ones to throw away." (Linus Pauling)
On Fri, Feb 27, 2026 at 8:09 AM Fujii Masao <masao.fujii@gmail.com> wrote: > I'm fine with this direction, but I think it should be handled as a separate > improvement to the \d meta-commands, rather than as part of the current patch > extending \dRp+, \dRs+, and \dX+. > > I'm thinking to first commit the v3 patch so that comments on publications, > subscriptions, and extended statistics can be viewed via \d. I've pushed the v3 patch. Thanks! Regards, -- Fujii Masao