DOCS: ALTER PUBLICATION - Synopsis for DROP is a bit misleading
I noticed that the ALTER PUBLICATION synopsis is misleading for the DROP part.
CURRENTLY [1]https://www.postgresql.org/docs/devel/sql-alterpublication.html
----------
ALTER PUBLICATION name ADD publication_object [, ...]
ALTER PUBLICATION name SET publication_object [, ...]
ALTER PUBLICATION name DROP publication_object [, ...]
...
where publication_object is one of:
TABLE [ ONLY ] table_name [ * ] [ ( column_name [, ... ] ) ] [
WHERE ( expression ) ] [, ... ]
TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
----------
But
- You cannot specify a column list when doing ALTER PUBLICATION ...
DROP TABLE ...
- You cannot specify a WHERE clause when doing ALTER PUBLICATION ...
DROP TABLE ...
test_pub=# CREATE TABLE T1(C1 INT,C2 INT);
CREATE TABLE
test_pub=# CREATE PUBLICATION P1 FOR TABLE T1(C1,C2);
CREATE PUBLICATION
test_pub=# ALTER PUBLICATION P1 DROP TABLE T1(C1,C2);
ERROR: column list must not be specified in ALTER PUBLICATION ... DROP
test_pub=# ALTER PUBLICATION P1 DROP TABLE T1 WHERE (C1=99);
ERROR: cannot use a WHERE clause when removing a table from a publication
======
It seemed misleading for the synopsis to imply something is allowed,
but then have qualifying notes in the description saying it is not
allowed, and then have errors at runtime for yet more things that are
not allowed that the qualifying notes neglected to mention.
Would it be better to make the synopsis more correct in the first place?
e.g. something like this...
SUGGESTION
----------
ALTER PUBLICATION name ADD publication_object [, ...]
ALTER PUBLICATION name SET publication_object [, ...]
ALTER PUBLICATION name DROP publication_drop_object [, ...]
...
where publication_object is one of:
TABLE [ ONLY ] table_name [ * ] [ ( column_name [, ... ] ) ] [
WHERE ( expression ) ] [, ... ]
TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
where publication_drop_object is one of:
TABLE [ ONLY ] table_name [ * ] [, ... ]
TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
----------
Thoughts?
Attached is a patch that does the same.
~~~
Alternatively, if people feel the synopsis is OK as-is, then I feel
that at least we have to put more qualifications in the description to
say that column lists must not be specified when using DROP.
======
[1]: https://www.postgresql.org/docs/devel/sql-alterpublication.html
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
alter_publication_synopsis_drop.diffapplication/octet-stream; name=alter_publication_synopsis_drop.diffDownload
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index d5ea383..01b45bc 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -23,7 +23,7 @@ PostgreSQL documentation
<synopsis>
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> ADD <replaceable class="parameter">publication_object</replaceable> [, ...]
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> SET <replaceable class="parameter">publication_object</replaceable> [, ...]
-ALTER PUBLICATION <replaceable class="parameter">name</replaceable> DROP <replaceable class="parameter">publication_object</replaceable> [, ...]
+ALTER PUBLICATION <replaceable class="parameter">name</replaceable> DROP <replaceable class="parameter">publication_drop_object</replaceable> [, ...]
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <replaceable>new_name</replaceable>
@@ -32,6 +32,11 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE ( <replaceable class="parameter">expression</replaceable> ) ] [, ... ]
TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
+
+<phrase>where <replaceable class="parameter">publication_drop_object</replaceable> is one of:</phrase>
+
+ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
+ TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
</synopsis>
</refsynopsisdiv>
@@ -57,8 +62,7 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
<literal>DROP TABLES IN SCHEMA</literal> will not drop any schema tables
that were specified using
<link linkend="sql-createpublication-params-for-table"><literal>FOR TABLE</literal></link>/
- <literal>ADD TABLE</literal>, and the combination of <literal>DROP</literal>
- with a <literal>WHERE</literal> clause is not allowed.
+ <literal>ADD TABLE</literal>.
</para>
<para>
Bump. I found this old thread of mine had received no responses for
several months.
Any thoughts about the problem it describes?
======
Kind Regards,
Peter Smith.
Fujitsu Australia
On Wed, Nov 5, 2025 at 8:26 AM Peter Smith <smithpb2250@gmail.com> wrote:
Bump. I found this old thread of mine had received no responses for
several months.Any thoughts about the problem it describes?
+1 to fixing the misleading synopsis. The patch looks good to me.
Unless there are any objections, I'll go ahead and commit it.
Regards,
--
Fujii Masao
On Wed, Nov 5, 2025 at 1:44 PM Fujii Masao <masao.fujii@gmail.com> wrote:
On Wed, Nov 5, 2025 at 8:26 AM Peter Smith <smithpb2250@gmail.com> wrote:
Bump. I found this old thread of mine had received no responses for
several months.Any thoughts about the problem it describes?
+1 to fixing the misleading synopsis. The patch looks good to me.
Unless there are any objections, I'll go ahead and commit it.
I've pushed the patch. Thanks!
Regards,
--
Fujii Masao
On Wed, Nov 12, 2025 at 6:06 PM Fujii Masao <masao.fujii@gmail.com> wrote:
...
I've pushed the patch. Thanks!
Thanks for pushing it.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
On Wed, Nov 12, 2025 at 6:06 PM Fujii Masao <masao.fujii@gmail.com> wrote:
On Wed, Nov 5, 2025 at 1:44 PM Fujii Masao <masao.fujii@gmail.com> wrote:
On Wed, Nov 5, 2025 at 8:26 AM Peter Smith <smithpb2250@gmail.com> wrote:
Bump. I found this old thread of mine had received no responses for
several months.Any thoughts about the problem it describes?
+1 to fixing the misleading synopsis. The patch looks good to me.
Unless there are any objections, I'll go ahead and commit it.I've pushed the patch. Thanks!
Thanks for pushing that synopsis fix.
Just in case you are interested, I have another small CREATE/ALTER
PUBLICATION synopsis patch over here [1]/messages/by-id/CAHut+PsuHQE2o1-xpWGMTz3zfO+RZUvReu_bx3Tm3jPrMpM22Q@mail.gmail.com that needs some attention ;-)
======
[1]: /messages/by-id/CAHut+PsuHQE2o1-xpWGMTz3zfO+RZUvReu_bx3Tm3jPrMpM22Q@mail.gmail.com
Kind Regards,
Peter Smith.
Fujitsu Australia