MIME-Version: 1.0
In-Reply-To: 
 <CAJpy0uAv36NnfLH=t+XUbwF+o1DYvF4P+cFbwh9R2DvmRW7nQg@mail.gmail.com>
References: 
 <CAKFQuwY=WLF0OH8JE5T8S=aj0LBydiSn02fkRE73Sm_KSLRqJQ@mail.gmail.com>
 <78ff5cc9-268f-4be8-ae0b-c1a07dc24852@proxel.se>
 <CAKFQuwb3dG_tLFbWc_A_NMu-1b7xfGhPBa=dnAGptBT_CNBqLw@mail.gmail.com>
 <CAJpy0uAv36NnfLH=t+XUbwF+o1DYvF4P+cFbwh9R2DvmRW7nQg@mail.gmail.com>
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Tue, 7 Apr 2026 21:28:18 -0700
Message-ID: 
 <CAKFQuwbmDM_X44PwxUw2=och-cs1TMMtBvNPuaB_u5EBbaiG2A@mail.gmail.com>
Subject: Re: doc: Improve wal_level and effective_wal_level GUC around logical
 replication
To: shveta malik <shveta.malik@gmail.com>
Cc: Andreas Karlsson <andreas@proxel.se>,
	PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Content-Type: multipart/alternative; boundary="00000000000054cd83064eeb548d"
Archived-At: 
 <https://www.postgresql.org/message-id/CAKFQuwbmDM_X44PwxUw2%3Doch-cs1TMMtBvNPuaB_u5EBbaiG2A%40mail.gmail.com>
Precedence: bulk

--00000000000054cd83064eeb548d
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Thank you, and the others, for the reviews.

On Tuesday, April 7, 2026, shveta malik <shveta.malik@gmail.com> wrote:

> Few comments:
>
> 1)
> +        Running read-only queries on a standby server.
>
> Looks incomplete and disconnected from previous sentence.


Yeah, I missed that one.


>
> 2)
> +        level used by the system.  Namely, whether replica has been
> promoted to
> +        logical (minimal never promotes).
>
> We shall replace replica, logical, minimal with below
> <literal>replica</literal>
> <literal>logical</literal>
> <literal>minimal</literal>


Yeah, I need to do a markup pass too apparently.  Though I do question
whether we are being too rote about these.  In this sentence yes I use the
actual labels but it=E2=80=99s more about concept than talking about someth=
ing
you=E2=80=99d literally type somewhere.  One doesn=E2=80=99t promote a lite=
ral, they
promote the operating mode of the server which is then reflected by the
change of a value.


>
> Also shall we add 'wal_level'? Otherwise, 'replica' on its own could
> be understood as a replica server:
>
> Namely, whether wal_level replica has been promoted to ....


>
The preceding sentence to which =E2=80=9Cnamely=E2=80=9D links talks about =
the levels.  But
I=E2=80=99ll give it a second look.  From my reply above, writing =E2=80=9C=
WAL level has
been promoted to logical from replica=E2=80=9D, is probably a better struct=
ure.


> 3)
> +        The <xref linkend=3D"guc-effective-wal-level"/> parameter
> reports the actual
> +        level used by the system.  Namely, whether replica has been
> promoted to
> +        logical (minimal never promotes).
> +        This parameter can only be set at server start.
>
> "This" here is misleading. Does this refer to wal_level or
> effective_wal_level?


When talking about where/when a setting can specified, =E2=80=9Cthis=E2=80=
=9D always refers
to the setting being documented.  I=E2=80=99m doubtful of the need to rewor=
d things
so that some other setting being talked about doesn=E2=80=99t get confused
instead.  The fact that we say effective WAL level is basically a runtime
derived setting in the prior sentence reinforces this belief.  And we try
to keep this sentence consistently at the end of the description.  Maybe it
needs its own paragraph though?  I=E2=80=99ll consider that.


>
> 4)
> Below that is <literal>minimal</literal>,
>
> Shall we change "that" to <literal>replica</literal> to avoid any
> confusion?


I=E2=80=99m on the fence at the moment.  This entire section needs a relook=
 anyway
and I=E2=80=99ll keep all these in mind.

David J.

--00000000000054cd83064eeb548d
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div>Thank you, and the others, for the reviews.</div><div><br></div>On Tue=
sday, April 7, 2026, shveta malik &lt;<a href=3D"mailto:shveta.malik@gmail.=
com">shveta.malik@gmail.com</a>&gt; wrote:<br><blockquote class=3D"gmail_qu=
ote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex=
">Few comments:<br>
<br>
1)<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 Running read-only queries on a standby server.=
<br>
<br>
Looks incomplete and disconnected from previous sentence.</blockquote><div>=
<br></div><div>Yeah, I missed that one.</div><div>=C2=A0</div><blockquote c=
lass=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;=
padding-left:1ex">
<br>
2)<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 level used by the system.=C2=A0 Namely, whethe=
r replica has been promoted to<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 logical (minimal never promotes).<br>
<br>
We shall replace replica, logical, minimal with below<br>
&lt;literal&gt;replica&lt;/literal&gt;<br>
&lt;literal&gt;logical&lt;/literal&gt;<br>
&lt;literal&gt;minimal&lt;/literal&gt;</blockquote><div><br></div><div>Yeah=
, I need to do a markup pass too apparently.=C2=A0 Though I do question whe=
ther we are being too rote about these.=C2=A0 In this sentence yes I use th=
e actual labels but it=E2=80=99s more about concept than talking about some=
thing you=E2=80=99d literally type somewhere.=C2=A0 One doesn=E2=80=99t pro=
mote a literal, they promote the operating mode of the server which is then=
 reflected by the change of a value.</div><div>=C2=A0</div><blockquote clas=
s=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;pad=
ding-left:1ex">
<br>
Also shall we add &#39;wal_level&#39;? Otherwise, &#39;replica&#39; on its =
own could<br>
be understood as a replica server:<br>
<br>
Namely, whether wal_level replica has been promoted to ....</blockquote><bl=
ockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #=
ccc solid;padding-left:1ex"><br></blockquote><div>=C2=A0</div><div>The prec=
eding sentence to which =E2=80=9Cnamely=E2=80=9D links talks about the leve=
ls.=C2=A0 But I=E2=80=99ll give it a second look.=C2=A0 From my reply above=
, writing =E2=80=9CWAL level has been promoted to logical from replica=E2=
=80=9D, is probably a better structure.</div><div>=C2=A0</div><blockquote c=
lass=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;=
padding-left:1ex">
3)<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 The &lt;xref linkend=3D&quot;guc-effective-wal=
-<wbr>level&quot;/&gt; parameter<br>
reports the actual<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 level used by the system.=C2=A0 Namely, whethe=
r replica has been promoted to<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 logical (minimal never promotes).<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 This parameter can only be set at server start=
.<br>
<br>
&quot;This&quot; here is misleading. Does this refer to wal_level or effect=
ive_wal_level?</blockquote><div><br></div><div>When talking about where/whe=
n a setting can specified, =E2=80=9Cthis=E2=80=9D always refers to the sett=
ing being documented.=C2=A0 I=E2=80=99m doubtful of the need to reword thin=
gs so that some other setting being talked about doesn=E2=80=99t get confus=
ed instead.=C2=A0 The fact that we say effective WAL level is basically a r=
untime derived setting in the prior sentence reinforces this belief.=C2=A0 =
And we try to keep this sentence consistently at the end of the description=
.=C2=A0 Maybe it needs its own paragraph though?=C2=A0 I=E2=80=99ll conside=
r that.</div><div>=C2=A0<br></div><blockquote class=3D"gmail_quote" style=
=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
4)<br>
Below that is &lt;literal&gt;minimal&lt;/literal&gt;,<br>
<br>
Shall we change &quot;that&quot; to &lt;literal&gt;replica&lt;/literal&gt; =
to avoid any confusion?</blockquote><div><br></div><div>I=E2=80=99m on the =
fence at the moment.=C2=A0 This entire section needs a relook anyway and I=
=E2=80=99ll keep all these in mind.</div><div><br></div><div>David J.</div>

--00000000000054cd83064eeb548d--