Horton

Thread

Commits

  1. doc: Fix incorrect synopsis for ALTER PUBLICATION ... DROP ...

  1. DOCS: ALTER PUBLICATION - Synopsis for DROP is a bit misleading

    Peter Smith <smithpb2250@gmail.com> — 2025-06-26T05:17:00Z

    I noticed that the ALTER PUBLICATION synopsis is misleading for the DROP part.

CURRENTLY [1]
----------
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

  2. Re: DOCS: ALTER PUBLICATION - Synopsis for DROP is a bit misleading

    Peter Smith <smithpb2250@gmail.com> — 2025-11-04T23:25:58Z

    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

  3. Re: DOCS: ALTER PUBLICATION - Synopsis for DROP is a bit misleading

    Fujii Masao <masao.fujii@gmail.com> — 2025-11-05T04:44:03Z

    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

  4. Re: DOCS: ALTER PUBLICATION - Synopsis for DROP is a bit misleading

    Fujii Masao <masao.fujii@gmail.com> — 2025-11-12T07:05:58Z

    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

  5. Re: DOCS: ALTER PUBLICATION - Synopsis for DROP is a bit misleading

    Peter Smith <smithpb2250@gmail.com> — 2025-11-12T22:31:52Z

    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

  6. Re: DOCS: ALTER PUBLICATION - Synopsis for DROP is a bit misleading

    Peter Smith <smithpb2250@gmail.com> — 2025-11-14T01:27:36Z

    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] that needs some attention ;-)

======
[1] https://www.postgresql.org/message-id/CAHut%2BPsuHQE2o1-xpWGMTz3zfO%2BRZUvReu_bx3Tm3jPrMpM22Q%40mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia