Show comments in \dRp+, \dRs+, and \dX+ psql meta-commands

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]/messages/by-id/82b25785-0dc1-46d6-93ac-ce385a3a0bfc@uni-muenster.de)

[1]: /messages/by-id/82b25785-0dc1-46d6-93ac-ce385a3a0bfc@uni-muenster.de
/messages/by-id/82b25785-0dc1-46d6-93ac-ce385a3a0bfc@uni-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 before the 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 before the 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.

/messages/by-id/26476097-B1C1-4BA8-AA92-0AD0B8EC7190@gmail.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 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