DOCS - Add missing EXCEPT parameter description to ALTER PUBLICATION

On Tue, Jun 9, 2026 at 10:12 AM Nisha Moond <nisha.moond412@gmail.com> wrote:

Hi Hackers,

As Peter noted in [1], the ALTER PUBLICATION documentation is missing
a parameter description for the EXCEPT clause. Ref: Commit fd36606
introduced the EXCEPT clause.

Attached is a simple patch to document the clause and its behavior.

[1] /messages/by-id/CAHut+Ps3sghX4qv1jehqMgvZG7DmUoAFqgjmVc5xUy+v5kHN3w@mail.gmail.com

The patch LGTM.

I have one more point to discuss. The EXCEPT implementation also
introduced a new ALTER-PUB variation where users can convert an ALL
TABLE to ALL SEQ and vice versa. We have not explained that anywhere.
I am not sure if a one-line explanation can be added. If not, I think
we can at-least add an example at the end for the same. Thoughts?

The existing examples are:

~~
Replace the table list in the publication's EXCEPT clause:
ALTER PUBLICATION mypublication SET ALL TABLES EXCEPT (TABLE users,
departments);

Reset the publication to be a FOR ALL TABLES publication with no
excluded tables:
ALTER PUBLICATION mypublication SET ALL TABLES;
~~

We can add one more:
Convert an ALL TABLES publication to ALL SEQUENCES one:
ALTER PUBLICATION mypublication SET ALL SEQUENCES;

thanks
Shveta

On Tue, Jun 9, 2026 at 10:52 AM shveta malik <shveta.malik@gmail.com> wrote:

On Tue, Jun 9, 2026 at 10:12 AM Nisha Moond <nisha.moond412@gmail.com> wrote:

Hi Hackers,

As Peter noted in [1], the ALTER PUBLICATION documentation is missing
a parameter description for the EXCEPT clause. Ref: Commit fd36606
introduced the EXCEPT clause.

Attached is a simple patch to document the clause and its behavior.

[1] /messages/by-id/CAHut+Ps3sghX4qv1jehqMgvZG7DmUoAFqgjmVc5xUy+v5kHN3w@mail.gmail.com

The patch LGTM.

I have one more point to discuss. The EXCEPT implementation also
introduced a new ALTER-PUB variation where users can convert an ALL
TABLE to ALL SEQ and vice versa. We have not explained that anywhere.
I am not sure if a one-line explanation can be added. If not, I think
we can at-least add an example at the end for the same. Thoughts?

The existing examples are:

~~
Replace the table list in the publication's EXCEPT clause:
ALTER PUBLICATION mypublication SET ALL TABLES EXCEPT (TABLE users,
departments);

Reset the publication to be a FOR ALL TABLES publication with no
excluded tables:
ALTER PUBLICATION mypublication SET ALL TABLES;
~~

We can add one more:
Convert an ALL TABLES publication to ALL SEQUENCES one:
ALTER PUBLICATION mypublication SET ALL SEQUENCES;

Okay, I see we already have this line in doc in initial explanation:

The SET ALL TABLES clause can transform an empty publication, or one
defined for ALL SEQUENCES (or both ALL TABLES and ALL SEQUENCES), into
a publication defined for ALL TABLES. Likewise, SET ALL SEQUENCES can
convert an empty publication, or one defined for ALL TABLES (or both
ALL TABLES and ALL SEQUENCES), into a publication defined for ALL
SEQUENCES.
~~

So please ignore my comment about a one-line explanation. An example
may be added though (if others also think so).

thanks
Shveta

Hi Nisha,

Thanks for following-up on this...

The patch LGTM in general, but here are a few comments.

======

1.
+   <varlistentry>
+    <term><literal>EXCEPT</literal></term>
+    <listitem>
+     <para>
+      This clause specifies a list of tables to be excluded from the
+      publication when used with <literal>SET ALL TABLES</literal>.  If
+      <literal>EXCEPT</literal> is specified, the existing exclusion list is
+      replaced with the specified tables.  If <literal>EXCEPT</literal> is
+      omitted, any existing table exclusions are removed.  See
+      <xref linkend="sql-createpublication-params-for-except-table"/> for
+      details.
+     </para>
+    </listitem>
+   </varlistentry>

1a.
I think reversing the first sentence wording makes it simpler.

SUGGESTION
This clause can be used with <literal>SET ALL TABLES</literal> to
specify a list of tables to be excluded from the publication.

~~~

1b.
The term is written differently to how you wrote it in your other thread [1]/messages/by-id/CABdArM5sw4Q1ZU8HGdo4BSc1A_+8xtUNq17j6wcir=yMUy19Cg@mail.gmail.com.

Here, you write the term as style #1:
<term><literal>EXCEPT</literal></term>

But, in the other thread you wrote the same term as style #2:
<term><literal>EXCEPT ( <replaceable
class="parameter">except_table_object</replaceable> [, ... ]
)</literal></term>

I am not sure which way is better. If we are eventually going to put
all variations of EXCEPT in the same place then maybe style #1 is
best; OTOH, if we anticipate separate descriptions for the "EXCEPT
(TABLE ...)" and "EXCEPT (SEQUENCE ...)" then maybe style #2 is best.

~~~

1c.
The xref looks a bit strange because it renders like "See EXCEPT for
details", but we are already looking at "EXCEPT", just not the same
one. Perhaps it should be changed so it renders like "See CREATE
PUBLICATION ... EXCEPT for details".

======
[1]: /messages/by-id/CABdArM5sw4Q1ZU8HGdo4BSc1A_+8xtUNq17j6wcir=yMUy19Cg@mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia

On Tue, Jun 9, 2026 at 12:12 PM Peter Smith <smithpb2250@gmail.com> wrote:

Hi Nisha,

Thanks for following-up on this...

The patch LGTM in general, but here are a few comments.

Thanks for the review.

======

1.
+   <varlistentry>
+    <term><literal>EXCEPT</literal></term>
+    <listitem>
+     <para>
+      This clause specifies a list of tables to be excluded from the
+      publication when used with <literal>SET ALL TABLES</literal>.  If
+      <literal>EXCEPT</literal> is specified, the existing exclusion list is
+      replaced with the specified tables.  If <literal>EXCEPT</literal> is
+      omitted, any existing table exclusions are removed.  See
+      <xref linkend="sql-createpublication-params-for-except-table"/> for
+      details.
+     </para>
+    </listitem>
+   </varlistentry>

1a.
I think reversing the first sentence wording makes it simpler.

SUGGESTION
This clause can be used with <literal>SET ALL TABLES</literal> to
specify a list of tables to be excluded from the publication.

I originally kept it consistent with the wording used in the CREATE
PUBLICATION doc, but I agree with your suggestion. Updated
accordingly.

~~~

1b.
The term is written differently to how you wrote it in your other thread [1].

Here, you write the term as style #1:
<term><literal>EXCEPT</literal></term>

But, in the other thread you wrote the same term as style #2:
<term><literal>EXCEPT ( <replaceable
class="parameter">except_table_object</replaceable> [, ... ]
)</literal></term>

I am not sure which way is better. If we are eventually going to put
all variations of EXCEPT in the same place then maybe style #1 is
best; OTOH, if we anticipate separate descriptions for the "EXCEPT
(TABLE ...)" and "EXCEPT (SEQUENCE ...)" then maybe style #2 is best.

I think we should keep style #1, as it is consistent with the style
used in create_publication.sgml.

I'll also update my other thread to follow the same style so things
remain consistent until this patch is committed.

~~~

1c.
The xref looks a bit strange because it renders like "See EXCEPT for
details", but we are already looking at "EXCEPT", just not the same
one. Perhaps it should be changed so it renders like "See CREATE
PUBLICATION ... EXCEPT for details".

Makes sense. Fixed.
~~

Attached v2 patch.

--
Thanks,
Nisha

On Tue, Jun 9, 2026 at 10:55 AM shveta malik <shveta.malik@gmail.com> wrote:

On Tue, Jun 9, 2026 at 10:52 AM shveta malik <shveta.malik@gmail.com> wrote:

On Tue, Jun 9, 2026 at 10:12 AM Nisha Moond <nisha.moond412@gmail.com> wrote:

Hi Hackers,

As Peter noted in [1], the ALTER PUBLICATION documentation is missing
a parameter description for the EXCEPT clause. Ref: Commit fd36606
introduced the EXCEPT clause.

Attached is a simple patch to document the clause and its behavior.

[1] /messages/by-id/CAHut+Ps3sghX4qv1jehqMgvZG7DmUoAFqgjmVc5xUy+v5kHN3w@mail.gmail.com

The patch LGTM.

Thanks for the review.

I have one more point to discuss. The EXCEPT implementation also
introduced a new ALTER-PUB variation where users can convert an ALL
TABLE to ALL SEQ and vice versa. We have not explained that anywhere.
I am not sure if a one-line explanation can be added. If not, I think
we can at-least add an example at the end for the same. Thoughts?

The existing examples are:

~~
Replace the table list in the publication's EXCEPT clause:
ALTER PUBLICATION mypublication SET ALL TABLES EXCEPT (TABLE users,
departments);

Reset the publication to be a FOR ALL TABLES publication with no
excluded tables:
ALTER PUBLICATION mypublication SET ALL TABLES;
~~

We can add one more:
Convert an ALL TABLES publication to ALL SEQUENCES one:
ALTER PUBLICATION mypublication SET ALL SEQUENCES;

Okay, I see we already have this line in doc in initial explanation:

The SET ALL TABLES clause can transform an empty publication, or one
defined for ALL SEQUENCES (or both ALL TABLES and ALL SEQUENCES), into
a publication defined for ALL TABLES. Likewise, SET ALL SEQUENCES can
convert an empty publication, or one defined for ALL TABLES (or both
ALL TABLES and ALL SEQUENCES), into a publication defined for ALL
SEQUENCES.
~~

So please ignore my comment about a one-line explanation. An example
may be added though (if others also think so).

I have added the suggested example in v2. I think it can remain in the
same patch, but let me know if you'd prefer it as a separate patch.

--
Thanks,
Nisha

On Wed, Jun 10, 2026 at 12:15 PM Nisha Moond <nisha.moond412@gmail.com> wrote:

On Tue, Jun 9, 2026 at 10:55 AM shveta malik <shveta.malik@gmail.com> wrote:

On Tue, Jun 9, 2026 at 10:52 AM shveta malik <shveta.malik@gmail.com> wrote:

On Tue, Jun 9, 2026 at 10:12 AM Nisha Moond <nisha.moond412@gmail.com> wrote:

Hi Hackers,

As Peter noted in [1], the ALTER PUBLICATION documentation is missing
a parameter description for the EXCEPT clause. Ref: Commit fd36606
introduced the EXCEPT clause.

Attached is a simple patch to document the clause and its behavior.

[1] /messages/by-id/CAHut+Ps3sghX4qv1jehqMgvZG7DmUoAFqgjmVc5xUy+v5kHN3w@mail.gmail.com

The patch LGTM.

Thanks for the review.

I have one more point to discuss. The EXCEPT implementation also
introduced a new ALTER-PUB variation where users can convert an ALL
TABLE to ALL SEQ and vice versa. We have not explained that anywhere.
I am not sure if a one-line explanation can be added. If not, I think
we can at-least add an example at the end for the same. Thoughts?

The existing examples are:

~~
Replace the table list in the publication's EXCEPT clause:
ALTER PUBLICATION mypublication SET ALL TABLES EXCEPT (TABLE users,
departments);

Reset the publication to be a FOR ALL TABLES publication with no
excluded tables:
ALTER PUBLICATION mypublication SET ALL TABLES;
~~

We can add one more:
Convert an ALL TABLES publication to ALL SEQUENCES one:
ALTER PUBLICATION mypublication SET ALL SEQUENCES;

Okay, I see we already have this line in doc in initial explanation:

The SET ALL TABLES clause can transform an empty publication, or one
defined for ALL SEQUENCES (or both ALL TABLES and ALL SEQUENCES), into
a publication defined for ALL TABLES. Likewise, SET ALL SEQUENCES can
convert an empty publication, or one defined for ALL TABLES (or both
ALL TABLES and ALL SEQUENCES), into a publication defined for ALL
SEQUENCES.
~~

So please ignore my comment about a one-line explanation. An example
may be added though (if others also think so).

I have added the suggested example in v2. I think it can remain in the
same patch, but let me know if you'd prefer it as a separate patch.

No, a single patch is fine. v2 LGTM.

thanks
Shveta

On Tue, Jun 9, 2026 at 10:12 AM Nisha Moond <nisha.moond412@gmail.com> wrote:

As Peter noted in [1], the ALTER PUBLICATION documentation is missing
a parameter description for the EXCEPT clause. Ref: Commit fd36606
introduced the EXCEPT clause.

But, we also don't have an explanation for SET { publication_object [,
...] | publication_all_object ..} for which EXCEPT is a sub-command.
So what justifies to add a separate explanation for EXCEPT in ALTER
PUBLICATION docs?

--
With Regards,
Amit Kapila.

On Wed, Jun 10, 2026 at 9:17 PM Amit Kapila <amit.kapila16@gmail.com> wrote:

On Tue, Jun 9, 2026 at 10:12 AM Nisha Moond <nisha.moond412@gmail.com> wrote:

As Peter noted in [1], the ALTER PUBLICATION documentation is missing
a parameter description for the EXCEPT clause. Ref: Commit fd36606
introduced the EXCEPT clause.

But, we also don't have an explanation for SET { publication_object [,
...] | publication_all_object ..} for which EXCEPT is a sub-command.
So what justifies to add a separate explanation for EXCEPT in ALTER
PUBLICATION docs?

If not here, then the information about would have to be added in the
"Description" part instead. Yes, maybe that is OK for now.

I think this patch is also anticipating the other EXCEPT enhancements
"FOR ALL SEQUENCES EXCEPT..." [1]/messages/by-id/CAHut+Pt6O3YD8h61RCtzMrRwgvS=RDRNf4KuXAUn1WYnoFU_uQ@mail.gmail.com and "FOR TABLES IN SCHEMA EXCEPT..."
[2]: /messages/by-id/CABdArM5sw4Q1ZU8HGdo4BSc1A_+8xtUNq17j6wcir=yMUy19Cg@mail.gmail.com
exclusions. Putting all those exclusion notes in the "Description"
part would cause too much clutter IMO. So this patch is just giving a
place for those other threads to put their notes today, instead of
requiring churning everything to introduce an "EXCEPT" part later
anyway.

======
[1]: /messages/by-id/CAHut+Pt6O3YD8h61RCtzMrRwgvS=RDRNf4KuXAUn1WYnoFU_uQ@mail.gmail.com
[2]: /messages/by-id/CABdArM5sw4Q1ZU8HGdo4BSc1A_+8xtUNq17j6wcir=yMUy19Cg@mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia

Hi Nisha,

Comments for patch v2-0001.

======

1.
In addition, SET ALL TABLES can be used to update the tables specified
in the EXCEPT clause of a FOR ALL TABLES publication. If EXCEPT is
specified with a list of tables, the existing exclusion list is
replaced with the specified tables. If EXCEPT is omitted, the existing
exclusion list is cleared.

~

The page already has the above test in the "Description".

I think one motivation of adding the "EXCEPT" part is to remove
clutter from the "Description", but currently there is a lot of
repetition. The "Description" can be pruned:

SUGGESTION
In addition, SET ALL TABLES can be used to update the tables specified
in the EXCEPT clause.

(and the EXCEPT above should link to the EXCEPT part)

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

On Thu, Jun 11, 2026 at 6:06 AM Peter Smith <smithpb2250@gmail.com> wrote:

On Wed, Jun 10, 2026 at 9:17 PM Amit Kapila <amit.kapila16@gmail.com> wrote:

On Tue, Jun 9, 2026 at 10:12 AM Nisha Moond <nisha.moond412@gmail.com> wrote:

As Peter noted in [1], the ALTER PUBLICATION documentation is missing
a parameter description for the EXCEPT clause. Ref: Commit fd36606
introduced the EXCEPT clause.

But, we also don't have an explanation for SET { publication_object [,
...] | publication_all_object ..} for which EXCEPT is a sub-command.
So what justifies to add a separate explanation for EXCEPT in ALTER
PUBLICATION docs?

If not here, then the information about would have to be added in the
"Description" part instead. Yes, maybe that is OK for now.

I see that already information related to EXCEPT is present in the
Description section.

I think this patch is also anticipating the other EXCEPT enhancements
"FOR ALL SEQUENCES EXCEPT..." [1] and "FOR TABLES IN SCHEMA EXCEPT..."
[2]. Those will also want to document special notes about altering
exclusions. Putting all those exclusion notes in the "Description"
part would cause too much clutter IMO.

Possible, but how to arrange that documentation is a separate
discussion. I feel we may want to point the links to the relevant
places in CREATE PUBLICATION.

--
With Regards,
Amit Kapila.

On Thu, Jun 11, 2026 at 8:28 AM Amit Kapila <amit.kapila16@gmail.com> wrote:

On Thu, Jun 11, 2026 at 6:06 AM Peter Smith <smithpb2250@gmail.com> wrote:

On Wed, Jun 10, 2026 at 9:17 PM Amit Kapila <amit.kapila16@gmail.com> wrote:

On Tue, Jun 9, 2026 at 10:12 AM Nisha Moond <nisha.moond412@gmail.com> wrote:

As Peter noted in [1], the ALTER PUBLICATION documentation is missing
a parameter description for the EXCEPT clause. Ref: Commit fd36606
introduced the EXCEPT clause.

But, we also don't have an explanation for SET { publication_object [,
...] | publication_all_object ..} for which EXCEPT is a sub-command.
So what justifies to add a separate explanation for EXCEPT in ALTER
PUBLICATION docs?

If not here, then the information about would have to be added in the
"Description" part instead. Yes, maybe that is OK for now.

I see that already information related to EXCEPT is present in the
Description section.

I think this patch is also anticipating the other EXCEPT enhancements
"FOR ALL SEQUENCES EXCEPT..." [1] and "FOR TABLES IN SCHEMA EXCEPT..."
[2]. Those will also want to document special notes about altering
exclusions. Putting all those exclusion notes in the "Description"
part would cause too much clutter IMO.

Possible, but how to arrange that documentation is a separate
discussion. I feel we may want to point the links to the relevant
places in CREATE PUBLICATION.

I agree that this has become more a question of documentation
structure, while also trying to avoid duplication between CREATE
PUBLICATION and ALTER PUBLICATION, which share the same parameters.

My inclination would be to revisit this once the other EXCEPT
variants, such as FOR ALL SEQUENCES EXCEPT and FOR TABLES IN SCHEMA
EXCEPT, have progressed further and reached RFC. At that point, the
overall documentation requirements and the best way to organize the
information across all EXCEPT variants should become much clearer.

For now, I'd prefer to revisit it later and proceed based on feedback
from others.

--
Thanks,
Nisha