Обсуждение: DOCS - "\d mytable" also shows any publications that publish mytable
I was looking at "\d" documentation yesterday. The psql table describe (e.g. "\d mytable") will display a list of any "Publications:" that are publishing the specified table. Somehow, this ability had escaped being mentioned in the psql reference documentation. Here is a trivial patch to fix that omission. ====== Kind Regards, Peter Smith. Fujitsu Australia
Вложения
See here [1] ====== [1] https://www.postgresql.org/docs/current/app-psql.html#APP-PSQL-META-COMMAND-D On Tue, Dec 23, 2025 at 8:07 AM Peter Smith <smithpb2250@gmail.com> wrote: > > I was looking at "\d" documentation yesterday. > > The psql table describe (e.g. "\d mytable") will display a list of any > "Publications:" that are publishing the specified table. Somehow, this > ability had escaped being mentioned in the psql reference > documentation. > > Here is a trivial patch to fix that omission. > > ====== > Kind Regards, > Peter Smith. > Fujitsu Australia
On 12/22/25 10:07 PM, Peter Smith wrote: > Here is a trivial patch to fix that omission. The patch looks good to me as this seems like useful information and I do not think it needs to be added in more places since e.g. \d+ does not have its own entry. Andreas
> On Dec 23, 2025, at 05:07, Peter Smith <smithpb2250@gmail.com> wrote:
>
> I was looking at "\d" documentation yesterday.
>
> The psql table describe (e.g. "\d mytable") will display a list of any
> "Publications:" that are publishing the specified table. Somehow, this
> ability had escaped being mentioned in the psql reference
> documentation.
>
> Here is a trivial patch to fix that omission.
>
> ======
> Kind Regards,
> Peter Smith.
> Fujitsu Australia
> <v1-0001-DOCS-psql-describe-table-can-list-publications.patch>
Not only publication, “\d table_name” also shows partition information:
```
evantest=# \d t_part;
Partitioned table "public.t_part"
Column | Type | Collation | Nullable | Default
--------+---------+-----------+----------+---------
id | integer | | |
val | integer | | |
Partition key: RANGE (id)
Publications:
"mypub"
Number of partitions: 3 (Use \d+ to list them.)
evantest=# \d t_part_p1;
Table "public.t_part_p1"
Column | Type | Collation | Nullable | Default
--------+---------+-----------+----------+---------
id | integer | | |
val | integer | | |
Partition of: t_part FOR VALUES FROM (0) TO (100)
```
As you updating this section, you may add “partition info” as well.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Tue, Dec 23, 2025 at 7:28 PM Chao Li <li.evan.chao@gmail.com> wrote:
>
>
>
> > On Dec 23, 2025, at 05:07, Peter Smith <smithpb2250@gmail.com> wrote:
> >
> > I was looking at "\d" documentation yesterday.
> >
> > The psql table describe (e.g. "\d mytable") will display a list of any
> > "Publications:" that are publishing the specified table. Somehow, this
> > ability had escaped being mentioned in the psql reference
> > documentation.
> >
> > Here is a trivial patch to fix that omission.
> >
> > ======
> > Kind Regards,
> > Peter Smith.
> > Fujitsu Australia
> > <v1-0001-DOCS-psql-describe-table-can-list-publications.patch>
>
> Not only publication, “\d table_name” also shows partition information:
>
> ```
> evantest=# \d t_part;
> Partitioned table "public.t_part"
> Column | Type | Collation | Nullable | Default
> --------+---------+-----------+----------+---------
> id | integer | | |
> val | integer | | |
> Partition key: RANGE (id)
> Publications:
> "mypub"
> Number of partitions: 3 (Use \d+ to list them.)
>
> evantest=# \d t_part_p1;
> Table "public.t_part_p1"
> Column | Type | Collation | Nullable | Default
> --------+---------+-----------+----------+---------
> id | integer | | |
> val | integer | | |
> Partition of: t_part FOR VALUES FROM (0) TO (100)
> ```
>
> As you updating this section, you may add “partition info” as well.
>
OK, I've added some text about partitions. See patch v2.
~~~
TBH, the \d and \d+ partition output looked strange to me.
test_pub=# \d+ tp
Partitioned table "public.tp"
Column | Type | Collation | Nullable | Default | Storage |
Compression | Stats target | Description
--------+---------+-----------+----------+---------+---------+-------------+--------------+-------------
a | integer | | | | plain |
| |
Partition key: RANGE (a)
Publications:
"pub1"
"pub3"
Partitions: tp1 FOR VALUES FROM (1) TO (10),
tp2 FOR VALUES FROM (10) TO (20)
For example:
a) Why isn't the "Partition key:" and "Partitions:" info kept together?
b) Why does the "Partitions:" list indentation look different?
Anyway, those are questions for another thread and another year.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Вложения
> On Dec 24, 2025, at 06:20, Peter Smith <smithpb2250@gmail.com> wrote: > > On Tue, Dec 23, 2025 at 7:28 PM Chao Li <li.evan.chao@gmail.com> wrote: >> >> >> >>> On Dec 23, 2025, at 05:07, Peter Smith <smithpb2250@gmail.com> wrote: >>> >>> I was looking at "\d" documentation yesterday. >>> >>> The psql table describe (e.g. "\d mytable") will display a list of any >>> "Publications:" that are publishing the specified table. Somehow, this >>> ability had escaped being mentioned in the psql reference >>> documentation. >>> >>> Here is a trivial patch to fix that omission. >>> >>> ====== >>> Kind Regards, >>> Peter Smith. >>> Fujitsu Australia >>> <v1-0001-DOCS-psql-describe-table-can-list-publications.patch> >> >> Not only publication, “\d table_name” also shows partition information: >> >> ``` >> evantest=# \d t_part; >> Partitioned table "public.t_part" >> Column | Type | Collation | Nullable | Default >> --------+---------+-----------+----------+--------- >> id | integer | | | >> val | integer | | | >> Partition key: RANGE (id) >> Publications: >> "mypub" >> Number of partitions: 3 (Use \d+ to list them.) >> >> evantest=# \d t_part_p1; >> Table "public.t_part_p1" >> Column | Type | Collation | Nullable | Default >> --------+---------+-----------+----------+--------- >> id | integer | | | >> val | integer | | | >> Partition of: t_part FOR VALUES FROM (0) TO (100) >> ``` >> >> As you updating this section, you may add “partition info” as well. >> > > OK, I've added some text about partitions. See patch v2. > > ~~~ > > TBH, the \d and \d+ partition output looked strange to me. > > test_pub=# \d+ tp > Partitioned table "public.tp" > Column | Type | Collation | Nullable | Default | Storage | > Compression | Stats target | Description > --------+---------+-----------+----------+---------+---------+-------------+--------------+------------- > a | integer | | | | plain | > | | > Partition key: RANGE (a) > Publications: > "pub1" > "pub3" > Partitions: tp1 FOR VALUES FROM (1) TO (10), > tp2 FOR VALUES FROM (10) TO (20) > > For example: > a) Why isn't the "Partition key:" and "Partitions:" info kept together? I guess it shows the plus stuff after the regular stuff. > b) Why does the "Partitions:" list indentation look different? Yeah, the list indentation should be identical. > > Anyway, those are questions for another thread and another year. > > ====== > Kind Regards, > Peter Smith. > Fujitsu Australia > <v2-0001-DOCS-psql-describe-table-can-list-publications-an.patch> V2 looks good to me. Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
On Wed, Dec 24, 2025 at 8:41 AM Chao Li <li.evan.chao@gmail.com> wrote: > > > > > On Dec 24, 2025, at 06:20, Peter Smith <smithpb2250@gmail.com> wrote: > > > > On Tue, Dec 23, 2025 at 7:28 PM Chao Li <li.evan.chao@gmail.com> wrote: > >> > >> > >> > >>> On Dec 23, 2025, at 05:07, Peter Smith <smithpb2250@gmail.com> wrote: > >>> > >>> I was looking at "\d" documentation yesterday. > >>> > >>> The psql table describe (e.g. "\d mytable") will display a list of any > >>> "Publications:" that are publishing the specified table. Somehow, this > >>> ability had escaped being mentioned in the psql reference > >>> documentation. > >>> > >>> Here is a trivial patch to fix that omission. > >>> > >>> ====== > >>> Kind Regards, > >>> Peter Smith. > >>> Fujitsu Australia > >>> <v1-0001-DOCS-psql-describe-table-can-list-publications.patch> > >> > >> Not only publication, “\d table_name” also shows partition information: > >> > >> ``` > >> evantest=# \d t_part; > >> Partitioned table "public.t_part" > >> Column | Type | Collation | Nullable | Default > >> --------+---------+-----------+----------+--------- > >> id | integer | | | > >> val | integer | | | > >> Partition key: RANGE (id) > >> Publications: > >> "mypub" > >> Number of partitions: 3 (Use \d+ to list them.) > >> > >> evantest=# \d t_part_p1; > >> Table "public.t_part_p1" > >> Column | Type | Collation | Nullable | Default > >> --------+---------+-----------+----------+--------- > >> id | integer | | | > >> val | integer | | | > >> Partition of: t_part FOR VALUES FROM (0) TO (100) > >> ``` > >> > >> As you updating this section, you may add “partition info” as well. > >> > > > > OK, I've added some text about partitions. See patch v2. > > > > ~~~ > > > > TBH, the \d and \d+ partition output looked strange to me. > > > > test_pub=# \d+ tp > > Partitioned table "public.tp" > > Column | Type | Collation | Nullable | Default | Storage | > > Compression | Stats target | Description > > --------+---------+-----------+----------+---------+---------+-------------+--------------+------------- > > a | integer | | | | plain | > > | | > > Partition key: RANGE (a) > > Publications: > > "pub1" > > "pub3" > > Partitions: tp1 FOR VALUES FROM (1) TO (10), > > tp2 FOR VALUES FROM (10) TO (20) > > > > For example: > > a) Why isn't the "Partition key:" and "Partitions:" info kept together? > > I guess it shows the plus stuff after the regular stuff. > > > b) Why does the "Partitions:" list indentation look different? > > Yeah, the list indentation should be identical. > > > > > Anyway, those are questions for another thread and another year. > > > > ====== > > Kind Regards, > > Peter Smith. > > Fujitsu Australia > > <v2-0001-DOCS-psql-describe-table-can-list-publications-an.patch> > > V2 looks good to me. \d table also seems to display tablespaces, policies, and other objects. Should the documentation try to list all possible objects that can be shown? If maintaining a complete list is difficult, would a more general description like "Associated objects, including indexes, constraints, rules, publications, and so on, are also shown." be sufficient instead of enumerating everything? Regards, -- Fujii Masao
On Thu, Dec 25, 2025 at 11:45 AM Fujii Masao <masao.fujii@gmail.com> wrote: > ... > > \d table also seems to display tablespaces, policies, and other objects. > Should the documentation try to list all possible objects that can be shown? > > If maintaining a complete list is difficult, would a more general description > like "Associated objects, including indexes, constraints, rules, publications, > and so on, are also shown." be sufficient instead of enumerating everything? > Hi Fujii-San. Thanks for the review, and I agree with your point. I prefer the suggestion for this description to be "correct" and future-proof (albeit slightly generic). Listing too many details doesn't add much value IMO and will be forever in need of documentation maintenance. PSA v3. ====== Kind Regards, Peter Smith. Fujitsu Australia
Вложения
Ping. I thought this small DOCS patch had reached some consensus, but then the thread went silent for more than 2 weeks. So, I created a new CF entry [1] marked "ready for committer". Is there anything else I need to do to help get this one over the line? ====== [1] https://commitfest.postgresql.org/patch/6414/ Kind Regards, Peter Smith. Fujitsu Australia
On Wed, Jan 21, 2026 at 7:39 AM Peter Smith <smithpb2250@gmail.com> wrote: > > Ping. I thought this small DOCS patch had reached some consensus, but > then the thread went silent for more than 2 weeks. > > So, I created a new CF entry [1] marked "ready for committer". Is > there anything else I need to do to help get this one over the line? - table, the view definition if the relation is a view, a non-default - <link linkend="sql-altertable-replica-identity">replica - identity</link> setting and the + table, any partition tables, the view definition if the relation is a + view, a non-default <link linkend="sql-altertable-replica-identity"> + replica identity</link> setting and the This part doesn't seem to list all possible objects, so it would be better to add wording like "for example" or "such as". If this is meant to be illustrative rather than exhaustive, I'm not sure we need to add a new item like "any partition tables" this time here. Regarding whole patch, I'm not clear about whether this patch is worthwhile if it only adds phrasing like "such as" or "for example". That said, if some users currently interpret the list as exhaustive, this change could help clarify the intent... If we decide to commit this change, it seems fine not to backpatch it, since it's more of a documentation clarification than a clear bug fix. Regards, -- Fujii Masao
On Thu, Jan 22, 2026 at 2:24 PM Fujii Masao <masao.fujii@gmail.com> wrote: > ... > > - table, the view definition if the relation is a view, a non-default > - <link linkend="sql-altertable-replica-identity">replica > - identity</link> setting and the > + table, any partition tables, the view definition if the relation is a > + view, a non-default <link linkend="sql-altertable-replica-identity"> > + replica identity</link> setting and the > > This part doesn't seem to list all possible objects, so it would be better to > add wording like "for example" or "such as". OK. Reworded it like that > > If this is meant to be illustrative rather than exhaustive, I'm not sure > we need to add a new item like "any partition tables" this time here. > OK. Removed. > Regarding whole patch, I'm not clear about whether this patch is worthwhile > if it only adds phrasing like "such as" or "for example". That said, if some > users currently interpret the list as exhaustive, this change could help > clarify the intent... > Yes. The patch is not doing much now, but OTOH the reason for this patch adding the "missing" publication entry in the first place was precisely because I thought the docs page was was documenting exhaustive lists; so there might be some merit to clear up that illusion. > If we decide to commit this change, it seems fine not to backpatch it, > since it's more of a documentation clarification than a clear bug fix. > Agree. ~~~ PSA v4. ====== Kind Regards, Peter Smith Fujitsu Australia
Вложения
On Thu, Jan 22, 2026 at 3:15 PM Peter Smith <smithpb2250@gmail.com> wrote: > > Regarding whole patch, I'm not clear about whether this patch is worthwhile > > if it only adds phrasing like "such as" or "for example". That said, if some > > users currently interpret the list as exhaustive, this change could help > > clarify the intent... > > > > Yes. The patch is not doing much now, but OTOH the reason for this > patch adding the "missing" publication entry in the first place was > precisely because I thought the docs page was was documenting > exhaustive lists; so there might be some merit to clear up that > illusion. OK, let's commit the patch as a documentation improvement to reduce user confusion. > PSA v4. Thanks for updating the patch! I've applied a few small tweaks and attached an updated version. + Associated objects, such as indexes, constraints, rules, publications, + triggers, and so on, are also shown. For foreign tables, the I removed "and so on" because using both "such as" and "and so on" in the same sentence felt redundant. + more information is displayed, such as: any comments associated with I removed "such as" and instead added "for example" before "any comments", which felt more natural here at least for me. - identity</link> setting and the + identity</link> settings and the I'm not sure this change is necessary, so I restored the original wording. I also updated the commit message. Regards, -- Fujii Masao
Вложения
> On Jan 23, 2026, at 10:40, Fujii Masao <masao.fujii@gmail.com> wrote: > > On Thu, Jan 22, 2026 at 3:15 PM Peter Smith <smithpb2250@gmail.com> wrote: >>> Regarding whole patch, I'm not clear about whether this patch is worthwhile >>> if it only adds phrasing like "such as" or "for example". That said, if some >>> users currently interpret the list as exhaustive, this change could help >>> clarify the intent... >>> >> >> Yes. The patch is not doing much now, but OTOH the reason for this >> patch adding the "missing" publication entry in the first place was >> precisely because I thought the docs page was was documenting >> exhaustive lists; so there might be some merit to clear up that >> illusion. > > OK, let's commit the patch as a documentation improvement to > reduce user confusion. > >> PSA v4. > > Thanks for updating the patch! I've applied a few small tweaks and > attached an updated version. > > + Associated objects, such as indexes, constraints, rules, publications, > + triggers, and so on, are also shown. For foreign tables, the > > I removed "and so on" because using both "such as" and "and so on" > in the same sentence felt redundant. > > + more information is displayed, such as: any comments associated with > > I removed "such as" and instead added "for example" before "any comments", > which felt more natural here at least for me. > > - identity</link> setting and the > + identity</link> settings and the > > I'm not sure this change is necessary, so I restored the original wording. > > I also updated the commit message. > > Regards, > > -- > Fujii Masao > <v5-0001-doc-Clarify-that-d-and-d-output-lists-are-illustr.patch> ``` + Associated objects, such as indexes, constraints, rules,triggers, ``` A while-space is missed before “triggers”. I tried to render the page, on the rendered html page, the white-space is alsomissed. Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
v5 LGTM, except for the missing space that Chao has already reported. ====== Kind Regards, Peter Smith. Fujitsu Australia
On Fri, Jan 23, 2026 at 2:49 PM Peter Smith <smithpb2250@gmail.com> wrote: > > v5 LGTM, except for the missing space that Chao has already reported. Thanks to both of you for the review! I've addressed the comment and pushed the updated patch. Regards, -- Fujii Masao
On Mon, Jan 26, 2026 at 10:49 PM Fujii Masao <masao.fujii@gmail.com> wrote: > ... > I've addressed the comment and pushed the updated patch. Thanks for pushing and marking the CF entry as "comitted" ====== Kind Regards, Peter Smith. Fujitsu Australia