Improve CREATE/ALTER PUBLICATION syntax for EXCEPT

On Wed, Jul 22, 2026 at 1:43 PM Fujii Masao <masao.fujii@gmail.com> wrote:

Hi,

Attached is a small docs patch to improve the syntax and description of
the EXCEPT clause for CREATE/ALTER PUBLICATION.

The current synopsis for EXCEPT is a bit confusing because both the EXCEPT
clause and except_table_object contain repeated lists:

ALL TABLES [ EXCEPT ( except_table_object [, ... ] ) ]
where except_table_object is:
TABLE table_object [, ... ]

The patch simplifies this by describing the syntax directly:

ALL TABLES [ EXCEPT ( TABLE table_object [, [ TABLE ] table_object ] ... ) ]

and removes the separate except_table_object production. I think
this is simpler and easier to understand. Thought?

The patch also updates the ALTER PUBLICATION description. The current
wording says "adding tables/except tables/schemas", but EXCEPT entries
are not added with ADD; they are replaced or cleared with SET ALL TABLES.
The updated text reflects that and also notes that
ALTER SUBSCRIPTION ... REFRESH PUBLICATION is required for such changes
to take effect on subscribers.

It also includes a few minor wording and markup fixes nearby.

+1 for all the description and markup changes.

But for the synopsis to change, I am not so sure...

~~~

Some might say,

ALL TABLES [ EXCEPT ( TABLE table_object [, [ TABLE ] table_object ] ... ) ]

is simpler than:

ALL TABLES [ EXCEPT ( except_table_object [, ... ] ) ]

where except_table_object is:
TABLE table_object [, ... ]

~~~

But, soon [1]/messages/by-id/CABdArM5sw4Q1ZU8HGdo4BSc1A_+8xtUNq17j6wcir=yMUy19Cg@mail.gmail.com there will also be ALL SCHEMAS EXCEPT which can re-use
that same `table_object`

Is the expanded style,

ALL TABLES [ EXCEPT ( TABLE table_object [, [ TABLE ] table_object ] ... ) ]
TABLES IN SCHEMA [ EXCEPT ( TABLE table_object [, [ TABLE ]
table_object ] ... ) ]

still better than:

ALL TABLES [ EXCEPT ( except_table_object [, ... ] ) ]
TABLES IN SCHEMA [ EXCEPT ( except_table_object [, ... ] ) ]

where except_table_object is:
TABLE table_object [, ... ]

~~~

And, consider later when entire schemas may be excluded from FOR ALL TABLES

It will be easy to write in the synopsis as:

ALL TABLES [ EXCEPT ( except_table_object | except_schema_object [, ... ] ) ]

where except_table_object is:
TABLE table_object [, ... ]
where except_schema_object is:
SCHEMA schema_name [, ... ]

OTOH, it would be a big mess if you tried to expand that out without
having `except_table_object` and `except_schema_object`.

~~~

So, the suggested synopsis change might seem good today, but in a
couple of years IMO we'd probably want to change it back again.

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

Kind Regards,
Peter Smith
Fujitsu Australia

On Wed, Jul 22, 2026 at 1:35 PM Peter Smith <smithpb2250@gmail.com> wrote:

So, the suggested synopsis change might seem good today, but in a
couple of years IMO we'd probably want to change it back again.

Your point seems reasonable to me. So, how about keeping a reusable
production, but making it represent the entire EXCEPT table list
instead of a single list element?

ALL TABLES [ EXCEPT ( except_table_list ) ]
where except_table_list is:
TABLE table_object [, [ TABLE ] table_object ] ...

This avoids having list notation in both the EXCEPT clause and the definition
of except_table_object, which makes the current synopsis a bit hard to read.
It also keeps the EXCEPT syntax probably reusable for future command support.

Regards,

--
Fujii Masao

On Wed, Jul 22, 2026 at 9:51 PM Fujii Masao <masao.fujii@gmail.com> wrote:

On Wed, Jul 22, 2026 at 1:35 PM Peter Smith <smithpb2250@gmail.com> wrote:

So, the suggested synopsis change might seem good today, but in a
couple of years IMO we'd probably want to change it back again.

Your point seems reasonable to me. So, how about keeping a reusable
production, but making it represent the entire EXCEPT table list
instead of a single list element?

ALL TABLES [ EXCEPT ( except_table_list ) ]
where except_table_list is:
TABLE table_object [, [ TABLE ] table_object ] ...

This avoids having list notation in both the EXCEPT clause and the definition
of except_table_object, which makes the current synopsis a bit hard to read.

Actually, the current synopsis is consistent with other
already-existing double lists like:

publication_object [, ... ]
where publication_object is one of:
TABLE table_and_columns [, ... ]
TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]

Personally, I don't find those publication_object double lists hard to
read, but perhaps I'm just used to them.

It also keeps the EXCEPT syntax probably reusable for future command support.

Probably reusable how?

e.g. I imagine a future command enhancement where there is the ability
to also exclude entire schemas from FOR ALL TABLES.
Easily done by expanding the existing synopsis like this:

FOR ALL TABLES [ EXCEPT ( { except_table_object | except_schema_object
} [, ... ] ) ]
and except_table_object is:
TABLE table_object [, ... ]
and except_schema_object is:
SCHEMA schema_name [, ... ]

That would allow complete freedom for any complex variation like
FOR ALL TABLES EXCEPT (TABLE t1, SCHEMA s1,s2, TABLE t2,t3, SCHEMA s3);

OTOH, I don't see how you can re-work your `except_table_list` idea to
support that same flexibility, unless you did almost the same thing:

ALL TABLES [ EXCEPT ( { except_table_list | except_schema_list } [, ... ] ) ]
where except_table_list is:
TABLE table_object [, [ TABLE ] table_object ] ...
where except_schema_list is:
SCHEMA schema_name [, [ SCHEMA ] schema_name ] ...

But that circles back to where we are right now with the double-list
notation, and is more wordy than it needs to be.

~~~

Aside:

BTW, in case you are wondering why I did not suggest removing
`except_table_object` to simplify further like below:

FOR ALL TABLES [ EXCEPT ( except_table_or_schema_object [, ... ] ) ]
and except_table_or_schema_object is one of:
TABLE table_object [, ... ]
SCHEMA schema_name [, ... ]

That's because the upcoming FOR TABLES IN SCHEMA s EXCEPT
is going to want to re-use that `except_table_object`

~~~

To summarise.
- The patch-suggested list flattening for `except_table_list` looks
OK, but the status-quo also looks OK to me and is consistent with
other terms
- I think removing these double lists now may need to be reverted
sometime in the future

Anyway, if you still think the new `except_table_list` term with the
flattened list is better, that's fine by me.

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

On Thu, Jul 23, 2026 at 10:01 AM Peter Smith <smithpb2250@gmail.com> wrote:

To summarise.
- The patch-suggested list flattening for `except_table_list` looks
OK, but the status-quo also looks OK to me and is consistent with
other terms
- I think removing these double lists now may need to be reverted
sometime in the future

Fair enough. I may be the only one who prefers the proposed synopsis,
and the current form is probably better suited to future extensions,
so I've dropped that part for now.

The attached patch removes the synopsis changes and keeps
the other documentation improvements.

Regards,

--
Fujii Masao

Some review comments for v2.

1. (rendered from patch)
Likewise altering a publication to set ALL TABLES, to change the
EXCEPT list, or to set or unset ALL SEQUENCES also requires the
subscriber to refresh the publication.

~

The text there says "set or unset" ALL SEQUENCES, but it only says
"set" ALL TABLES.

AFAIK the SET will *replace* the kind of publication.

e.g.1
Assuming we start out a publication that has FOR ALL SEQUENCES
Then, ALTER ... SET ALL TABLES will effectively "unset" ALL SEQUENCES

e.g.2
Assuming we start out a publication that has FOR ALL TABLES
Then, ALTER ... SET ALL SEQUENCES will effectively "unset" ALL TABLES

~

It might be better not to say "unset" at all, but if you want to keep
it then maybe it ought to be said in both places.

~~~

2.
(probably out of scope for this patch)

IMO this "Description" is becoming overly-complicated by saying "Note
that" and "Note also that" etc.

It seems to me that anything that is a note belongs in the "Notes"
section (but the "Notes" section is strangely missing from this page)
so that the "Description" section can be much less cluttered. e.g.
Compare with Description for CREATE PUBLICATION page.

Anyway, perhaps refactoring to make a new "Notes" section is a patch
for another day, not now.

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