DOCS - CREATE PUBLICATION wording re 'ONLY' for partitioned tables.

On Oct 19, 2026, at 14:57, Peter Smith <smithpb2250@gmail.com> wrote:

Hi hackers.

(This is a DOCS improvement patch only)

This patch was originally in another thread, where it was suggested
[1] to post separately (here), since it is an independent improvement.

~

The "CREATE PUBLICATION" docs [2] say:
"This does not apply to a partitioned table, however."

It is ambiguous as to exactly what "this" refers to:
- does "this" mean just the '*' of the prior sentence?
- does "this" relate to the whole 'ONLY'/'*' discussion?

The patch removes the ambiguity. PSA v1.

======
[1] /messages/by-id/19bc00e8-ed58-488d-a727-5bca2445b795@gmail.com
[2] https://www.postgresql.org/docs/devel/sql-createpublication.html

Kind Regards,
Peter Smith.
Fujitsu Australia
<v1-0001-DOCS-Remove-ambiguous-wording-about-ONLY-for-part.patch>

I think this is an improvement by making the meaning of ONLY and * clearer.

I just have nit comment:
```
+ the publication, so they are never explicitly added to the publication.
```

“so they are never explicitly added to the publication” might be read as a child partition cannot be added explicitly, however I verified the following is valid:
```
CREATE TABLE p (id integer) PARTITION BY RANGE (id);
CREATE TABLE p1 PARTITION OF p FOR VALUES FROM (0) TO (100);
CREATE PUBLICATION pub FOR TABLE p, p1;
```

So, how about:
```
the publication, so they do not need to be explicitly added to the
publication.
```

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/

On Mon, Oct 19, 2026 at 1:42 PM Chao Li <li.evan.chao@gmail.com> wrote:

On Oct 19, 2026, at 14:57, Peter Smith <smithpb2250@gmail.com> wrote:

Hi hackers.

(This is a DOCS improvement patch only)

This patch was originally in another thread, where it was suggested
[1] to post separately (here), since it is an independent improvement.

~

The "CREATE PUBLICATION" docs [2] say:
"This does not apply to a partitioned table, however."

It is ambiguous as to exactly what "this" refers to:
- does "this" mean just the '*' of the prior sentence?
- does "this" relate to the whole 'ONLY'/'*' discussion?

The patch removes the ambiguity. PSA v1.

======
[1] /messages/by-id/19bc00e8-ed58-488d-a727-5bca2445b795@gmail.com
[2] https://www.postgresql.org/docs/devel/sql-createpublication.html

Kind Regards,
Peter Smith.
Fujitsu Australia
<v1-0001-DOCS-Remove-ambiguous-wording-about-ONLY-for-part.patch>

I think this is an improvement by making the meaning of ONLY and * clearer.

I just have nit comment:
```
+ the publication, so they are never explicitly added to the publication.
```

“so they are never explicitly added to the publication” might be read as a child partition cannot be added explicitly, however I verified the following is valid:
```
CREATE TABLE p (id integer) PARTITION BY RANGE (id);
CREATE TABLE p1 PARTITION OF p FOR VALUES FROM (0) TO (100);
CREATE PUBLICATION pub FOR TABLE p, p1;
```

So, how about:
```
the publication, so they do not need to be explicitly added to the
publication.
```

+1. I had the same thought while reviewing. Although the goal here is
just to clarify the point about ONLY, we can also make the subsequent
sentence less ambiguous in the same patch.

thanks
Shveta

On Mon, Oct 19, 2026 at 7:49 PM shveta malik <shveta.malik@gmail.com> wrote:

On Mon, Oct 19, 2026 at 1:42 PM Chao Li <li.evan.chao@gmail.com> wrote:

...

I think this is an improvement by making the meaning of ONLY and * clearer.

I just have nit comment:
```
+ the publication, so they are never explicitly added to the publication.
```

“so they are never explicitly added to the publication” might be read as a child partition cannot be added explicitly, however I verified the following is valid:
```
CREATE TABLE p (id integer) PARTITION BY RANGE (id);
CREATE TABLE p1 PARTITION OF p FOR VALUES FROM (0) TO (100);
CREATE PUBLICATION pub FOR TABLE p, p1;
```

So, how about:
```
the publication, so they do not need to be explicitly added to the
publication.
```

+1. I had the same thought while reviewing. Although the goal here is
just to clarify the point about ONLY, we can also make the subsequent
sentence less ambiguous in the same patch.

Hi Chao and Shveta.

Thanks for your review comments. I agree with you.

PSA patch v2, which also fixes the misleading "never" wording in the
original sentence.

======
Kind Regards,
Peter Smith.
Fujitsu Australia

Hi all

Thanks for your review comments. I agree with you.

PSA patch v2, which also fixes the misleading "never" wording in the
original sentence.

Thank you for creating another thread per my suggestion.
The patch V2 looks good to me.

It's completely optional but I noticed that ALTER PUBLICATION doc [1]https://www.postgresql.org/docs/devel/sql-alterpublication.html --- Name of an existing table. If ONLY is specified before the table_name, only that table is affected. If ONLY is not specified, the table and all its descendant tables (if any) are affected. Optionally, * can be specified after the table_name to explicitly indicate that descendant tables are included. ---
also mentions ONLY and '*' though ALTER PUBLICATION doc does not mention
partitioned table at all. How about adding the similar note to ALTER
doc? I know the main purpose of this patch is to remove ambiguous
sentence from CREATE PUBLICATION doc. But it could be worthwhile to
clarify how postgres behaves also in ALTER doc.

I tested myself and ALTER also ignores ONLY and * for partitioned table
as well.

[1]: https://www.postgresql.org/docs/devel/sql-alterpublication.html --- Name of an existing table. If ONLY is specified before the table_name, only that table is affected. If ONLY is not specified, the table and all its descendant tables (if any) are affected. Optionally, * can be specified after the table_name to explicitly indicate that descendant tables are included. ---
---
Name of an existing table. If ONLY is specified before the table_name,
only that table is affected. If ONLY is not specified, the table and all
its descendant tables (if any) are affected. Optionally, * can be
specified after the table_name to explicitly indicate that descendant
tables are included.
---

Regards,
Takeshi Ideriha

On Tue, Oct 20, 2026 at 11:16 AM Takeshi Ideriha
<iderihatakeshi@gmail.com> wrote:

Thank you for creating another thread per my suggestion.
The patch V2 looks good to me.

+1

It's completely optional but I noticed that ALTER PUBLICATION doc [1]
also mentions ONLY and '*' though ALTER PUBLICATION doc does not mention
partitioned table at all. How about adding the similar note to ALTER
doc? I know the main purpose of this patch is to remove ambiguous
sentence from CREATE PUBLICATION doc. But it could be worthwhile to
clarify how postgres behaves also in ALTER doc.

+1

The patch seems an improvement of the docs rather than fix of an incorrect
description. So it's sufficient to be committed only to master,
without backpatching
to stable branches?

Regards,

--
Fujii Masao

On Tue, Oct 20, 2026 at 1:16 PM Takeshi Ideriha
<iderihatakeshi@gmail.com> wrote:

Hi all

Thanks for your review comments. I agree with you.

PSA patch v2, which also fixes the misleading "never" wording in the
original sentence.

Thank you for creating another thread per my suggestion.
The patch V2 looks good to me.

It's completely optional but I noticed that ALTER PUBLICATION doc [1]
also mentions ONLY and '*' though ALTER PUBLICATION doc does not mention
partitioned table at all. How about adding the similar note to ALTER
doc? I know the main purpose of this patch is to remove ambiguous
sentence from CREATE PUBLICATION doc. But it could be worthwhile to
clarify how postgres behaves also in ALTER doc.

Hi Takeshi-San

Sure, I guess it makes sense for those paragraphs in CREATE and ALTER
to say the same thing.

(At least, it is easier to make them the same than to justify why they
shouldn't be.)

PSA v3.

======
Kind Regards,
Peter Smith.
Fujitsu Australia

The patch seems an improvement of the docs rather than fix of an incorrect
description. So it's sufficient to be committed only to master,
without backpatching
to stable branches?

+1
Current doc is not wrong. It seems to me pushing only to master is good.

Regards,
Takeshi Ideriha

Hi Peter

Hi Takeshi-San

Sure, I guess it makes sense for those paragraphs in CREATE and ALTER
to say the same thing.

(At least, it is easier to make them the same than to justify why they
shouldn't be.)

PSA v3.

Thank you for addressing my suggestion. V3 looks good to me. I also
believe the same wording works.

Regards,
Takeshi Ideriha

On Tue, Oct 20, 2026 at 2:20 PM Takeshi Ideriha
<iderihatakeshi@gmail.com> wrote:

Thank you for addressing my suggestion. V3 looks good to me. I also
believe the same wording works.

Thanks for updating the patch!

+      For a partitioned table, <literal>ONLY</literal> and <literal>*</literal>
+      have no effect: its partitions are always implicitly considered part of
+      the publication, so they do not need to be added explicitly.

In ALTER PUBLICATION, "table_name" also applies to DROP and EXCEPT,
so seems the original wording needs to account for those cases.
How about:

For a partitioned table, <literal>ONLY</literal> and <literal>*</literal>
have no effect. When a partitioned table is included in a publication,
its partitions are implicitly included as well and need not be added
explicitly. For tables specified in <literal>EXCEPT</literal>, see the
description of
<link linkend="sql-createpublication-params-for-except-table"><literal>EXCEPT</literal></link>
in <xref linkend="sql-createpublication"/>.

</para>
-
<para>

Why is this blank line removed?

Regards,

--
Fujii Masao

On Thu, Oct 22, 2026 at 1:44 PM Fujii Masao <masao.fujii@gmail.com> wrote:

On Tue, Oct 20, 2026 at 2:20 PM Takeshi Ideriha
<iderihatakeshi@gmail.com> wrote:

Thank you for addressing my suggestion. V3 looks good to me. I also
believe the same wording works.

Thanks for updating the patch!

+      For a partitioned table, <literal>ONLY</literal> and <literal>*</literal>
+      have no effect: its partitions are always implicitly considered part of
+      the publication, so they do not need to be added explicitly.

In ALTER PUBLICATION, "table_name" also applies to DROP and EXCEPT,
so seems the original wording needs to account for those cases.
How about:

For a partitioned table, <literal>ONLY</literal> and <literal>*</literal>
have no effect. When a partitioned table is included in a publication,
its partitions are implicitly included as well and need not be added
explicitly. For tables specified in <literal>EXCEPT</literal>, see the
description of
<link linkend="sql-createpublication-params-for-except-table"><literal>EXCEPT</literal></link>
in <xref linkend="sql-createpublication"/>.

+1.

On Oct 22, 2026, at 16:14, Fujii Masao <masao.fujii@gmail.com> wrote:

On Tue, Oct 20, 2026 at 2:20 PM Takeshi Ideriha
<iderihatakeshi@gmail.com> wrote:

Thank you for addressing my suggestion. V3 looks good to me. I also
believe the same wording works.

Thanks for updating the patch!

+      For a partitioned table, <literal>ONLY</literal> and <literal>*</literal>
+      have no effect: its partitions are always implicitly considered part of
+      the publication, so they do not need to be added explicitly.

In ALTER PUBLICATION, "table_name" also applies to DROP and EXCEPT,
so seems the original wording needs to account for those cases.
How about:

For a partitioned table, <literal>ONLY</literal> and <literal>*</literal>
have no effect. When a partitioned table is included in a publication,
its partitions are implicitly included as well and need not be added
explicitly. For tables specified in <literal>EXCEPT</literal>, see the
description of
<link linkend="sql-createpublication-params-for-except-table"><literal>EXCEPT</literal></link>
in <xref linkend="sql-createpublication"/>.

I like the first part of your suggested change, “when a partitioned table is included in a publication”, but I don't think we need to mention EXCEPT separately. Maybe we could just replace “not be added explicitly” with “not be included explicitly”? I think that should cover the EXCEPT case as well.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/

Hi Peter,

I looked at v3. I agree ONLY/* have no effect for partitioned tables in
every ALTER PUBLICATION variant i.e OpenTableList() skips recursion
for RELKIND_PARTITIONED_TABLE regardless of ADD/SET/DROP/EXCEPT.

A few points,

1. Following on from Fujii's point that table_name in ALTER PUBLICATION
also covers DROP, the new note explains ONLY/* only in
terms of adding, which leaves DROP unclear. For example:

CREATE TABLE p (id int) PARTITION BY RANGE (id);
CREATE TABLE p1 PARTITION OF p FOR VALUES FROM (0) TO (100);
CREATE PUBLICATION c FOR TABLE p, p1;
ALTER PUBLICATION c DROP TABLE p *;
-- p1 remains in pg_publication_rel

whereas for a plain inheritance parent, DROP TABLE parent (without ONLY)
also removes the child. Maybe worth saying that dropping a
partitioned table does not remove partitions that were added to the
publication explicitly.

2. A minor point (pre-existing) In CREATE PUBLICATION, the same FOR TABLE
entry already ends with "When a partitioned table is added to a
publication, all of its existing and future partitions are implicitly
considered to be part of the publication...". Both the
old text and v3 repeat that a few lines above, so perhaps just "For a
partitioned table, ONLY and * have no effect." is enough there.

Regards,
Surya Poondla

On Oct 23, 2026, at 02:36, surya poondla <suryapoondla4@gmail.com> wrote:

Hi Peter,

I looked at v3. I agree ONLY/* have no effect for partitioned tables in every ALTER PUBLICATION variant i.e OpenTableList() skips recursion
for RELKIND_PARTITIONED_TABLE regardless of ADD/SET/DROP/EXCEPT.

A few points,

1. Following on from Fujii's point that table_name in ALTER PUBLICATION also covers DROP, the new note explains ONLY/* only in
terms of adding, which leaves DROP unclear. For example:

CREATE TABLE p (id int) PARTITION BY RANGE (id);
CREATE TABLE p1 PARTITION OF p FOR VALUES FROM (0) TO (100);
CREATE PUBLICATION c FOR TABLE p, p1;
ALTER PUBLICATION c DROP TABLE p *;
-- p1 remains in pg_publication_rel

whereas for a plain inheritance parent, DROP TABLE parent (without ONLY) also removes the child. Maybe worth saying that dropping a
partitioned table does not remove partitions that were added to the publication explicitly.

I don’t think this is a normal usage that we want to prompt. I’m afraid that describing details of such an edge case may just make users confused. In the meantime, I would challenge if that’s a bug. IMO, dropping “p *” should drop p1.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/