Re: pgsql: Doc: Explain about Column List feature.

On 2022-Sep-14, Peter Smith wrote:

> On Tue, Sep 13, 2022 at 10:11 PM Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> wrote:

> > On 2022-Sep-07, Amit Kapila wrote:

> > One more thing. There's a sect2 about combining column list. Part of it
> > seems pretty judgmental and I see no reason to have it in there; I
> > propose to remove it (it's not in this patch). I think we should just
> > say it doesn't work at present, here's how to work around it, and
> > perhaps even say that we may lift the restriction in the future. The
> > paragraph that starts with "Background:" is IMO out of place, and it
> > repeats the mistake that column lists are for security.
>
> It wasn't clear which part you felt was judgemental. I have removed
> the "Background" paragraph but I have otherwise left that section and
> Warning as-is because it still seemed useful for the user to know. You
> can change/remove it if you disagree.

I meant the Background part that you remove, yeah.

Looking at the rendered docs again, I notice that section "31.4.5.
Combining Multiple Column Lists" is *only* the red-tinted Warning block.
That seems quite odd. I am tempted to remove the sect2 heading for that
one too. I am now wondering how to split things between the normative bits
"It is not supported to have a subscription comprising several
publications where the same table has been published with different
column lists."

and the informative bits
"This means changing the column lists of the tables being subscribed
could cause inconsistency of column lists among publications, in which
case the ALTER PUBLICATION will be successful but later the walsender
on the publisher, or the subscriber may throw an error. In this
scenario, the user needs to recreate the subscription after adjusting
the column list or drop the problematic publication using ALTER
SUBSCRIPTION ... DROP PUBLICATION and then add it back after adjusting
the column list."

> > Lastly: In the create-publication reference page I think it would be
> > better to reword the Parameters section a bit. It mentions
> > FOR TABLE as a parameter, but the parameter is actually
> > <replaceable>table_name</replaceable>; and the row-filter and
> > column-list explanations are also put in there when they should be in
> > their own <replaceable>expression</> and <replaceable>column_name</>
> > varlistentries. I think splitting things that way would result in a
> > clearer explanation.
>
> IMO this should be proposed as a separate patch. Some of those things
> (e.g. FOR TABLE as a parameter) seem to have been written that way
> since PG10.

Agreed.

--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"Aprender sin pensar es inútil; pensar sin aprender, peligroso" (Confucio)