MIME-Version: 1.0
In-Reply-To: <33F33315-9A7D-41A2-9F37-0A361E5A4C7F@gmail.com>
References: 
 <CAKFQuwY=WLF0OH8JE5T8S=aj0LBydiSn02fkRE73Sm_KSLRqJQ@mail.gmail.com>
 <33F33315-9A7D-41A2-9F37-0A361E5A4C7F@gmail.com>
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Tue, 7 Apr 2026 20:10:45 -0700
Message-ID: 
 <CAKFQuwZBEJf5sq5oj-pM18Qu1eNP=fE7zRYAybeD2ifd1gmwXg@mail.gmail.com>
Subject: doc: Improve wal_level and effective_wal_level GUC around logical
 replication
To: Chao Li <li.evan.chao@gmail.com>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Content-Type: multipart/alternative; boundary="00000000000003a2a2064eea3fa1"
Archived-At: 
 <https://www.postgresql.org/message-id/CAKFQuwZBEJf5sq5oj-pM18Qu1eNP%3DfE7zRYAybeD2ifd1gmwXg%40mail.gmail.com>
Precedence: bulk

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

On Tuesday, April 7, 2026, Chao Li <li.evan.chao@gmail.com> wrote:
>
> > On Mar 4, 2026, at 23:55, David G. Johnston <david.g.johnston@gmail.com=
>
> wrote:
> >
> > Hi,
> >
> > In evaluating the proposed change to wal_level docs in [1] I found it t=
o
> be undesirable, but the discussion and my own review discovered some othe=
r
> changes that should be considered.
> >
> > Since effective_wal_level now exists, Logical Replication Getting
> Started needs to be updated.
> > Add links to the main topics that the different levels apply to.
> > Be explicit about the ordering of minimal, replica, and logical.
> > Move the behavior of effective_wal_level to the GUC for it, leaving
> behind just the pointer that wal_level is now just a "minimum".
> >
> > David J.
> >
> > [1] https://www.postgresql.org/message-id/CA%2Bv5N42vKtY17653eBH
> Fx%2BCw06E2fSmPrXmX2qKYG23%3D4Ycd7A%40mail.gmail.com
> > <v1-0001-doc-Add-some-clarity-around-wal_level.patch>
>
>
> A few comments:
>
> 1
> ```
> --- a/doc/src/sgml/logical-replication.sgml
> +++ b/doc/src/sgml/logical-replication.sgml
> @@ -3508,11 +3508,12 @@ pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l
> logfile
>    <title>Quick Setup</title>
>
>    <para>
> -   First set the configuration options in <filename>postgresql.conf</fil
> ename>:
> +   Ensure that <xref linkend=3D"guc-effective-wal-level"/> is at least
> replica
> +   (this is the default).
>  <programlisting>
> -wal_level =3D logical
> +SHOW effective_wal_level;
>  </programlisting>
> -   The other required settings have default values that are sufficient
> for a
> +   The other required settings also have default values that are
> sufficient for a
>     basic setup.
>    </para>
> ```
>
> I think wal_level should be at least =E2=80=9Clogical=E2=80=9D. I don=E2=
=80=99t get why did you
> change to =E2=80=9Creplica=E2=80=9D? It=E2=80=99s clear that we still nee=
d =E2=80=9Clogical=E2=80=9D to support
> logical replication.


A minimum setting of replica is automatically interpreted (i.e., effective
WAL level) as logical when necessary so the default setting of replica
doesn=E2=80=99t need to be changed anymore.  Seeing replica in effective WA=
L level
means no logical replication has been setup and the dba hasn=E2=80=99t redu=
ced the
system to minimal.  If one sees logical there, that works too.


> 2
> ```
> +        <literal>replica</literal>, which writes enough data to support
> +        WAL archiving (see <xref linkend=3D"continuous-archiving"/>) and
> +        physical replication (see <xref linkend=3D"streaming-replication
> "/>)
> +        Running read-only queries on a standby server. Below that is
> <literal>minimal</literal>,
> ```
>
> Here, =E2=80=9CRunning read-only =E2=80=A6=E2=80=9D sentence looks not sm=
ooth, and there is not a
> period for the last sentence before =E2=80=9CRunning". The old wording wa=
s
> =E2=80=9Cincluding running read-only =E2=80=A6.=E2=80=9D.
>

Yeah, I still stand by the whole of it but need to do another pass.

I do get that there likely wasn=E2=80=99t any ambiguity - even presented re=
plica,
minimal, logical - as to which was highest/middle/lower and being explicit
here maybe seems overly verbose.

Also, I added a qualifier regarding =E2=80=9Cprimary servers=E2=80=9D but a=
m now unsure
why.  Kinda concerned about logical where publisher and subscriber are not
mutually exclusive.

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

On Tuesday, April 7, 2026, Chao Li &lt;<a href=3D"mailto:li.evan.chao@gmail=
.com" target=3D"_blank">li.evan.chao@gmail.com</a>&gt; wrote:<blockquote cl=
ass=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;p=
adding-left:1ex">
&gt; On Mar 4, 2026, at 23:55, David G. Johnston &lt;<a href=3D"mailto:davi=
d.g.johnston@gmail.com" target=3D"_blank">david.g.johnston@gmail.com</a>&gt=
; wrote:<br>
&gt; <br>
&gt; Hi,<br>
&gt; <br>
&gt; In evaluating the proposed change to wal_level docs in [1] I found it =
to be undesirable, but the discussion and my own review discovered some oth=
er changes that should be considered.<br>
&gt; <br>
&gt; Since effective_wal_level now exists, Logical Replication Getting Star=
ted needs to be updated.<br>
&gt; Add links to the main topics that the different levels apply to.<br>
&gt; Be explicit about the ordering of minimal, replica, and logical.<br>
&gt; Move the behavior of effective_wal_level to the GUC for it, leaving be=
hind just the pointer that wal_level is now just a &quot;minimum&quot;.<br>
&gt; <br>
&gt; David J.<br>
&gt; <br>
&gt; [1] <a href=3D"https://www.postgresql.org/message-id/CA%2Bv5N42vKtY176=
53eBHFx%2BCw06E2fSmPrXmX2qKYG23%3D4Ycd7A%40mail.gmail.com" target=3D"_blank=
">https://www.postgresql.org/mes<wbr>sage-id/CA%2Bv5N42vKtY17653eBH<wbr>Fx%=
2BCw06E2fSmPrXmX2qKYG23%3D4<wbr>Ycd7A%40mail.gmail.com</a><br>
&gt; &lt;v1-0001-doc-Add-some-clarity-<wbr>around-wal_level.patch&gt;<br>
<br>
<br>
A few comments:<br>
<br>
1<br>
```<br>
--- a/doc/src/sgml/logical-replica<wbr>tion.sgml<br>
+++ b/doc/src/sgml/logical-replica<wbr>tion.sgml<br>
@@ -3508,11 +3508,12 @@ pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l l=
ogfile<br>
=C2=A0 =C2=A0&lt;title&gt;Quick Setup&lt;/title&gt;<br>
<br>
=C2=A0 =C2=A0&lt;para&gt;<br>
-=C2=A0 =C2=A0First set the configuration options in &lt;filename&gt;postgr=
esql.conf&lt;/fil<wbr>ename&gt;:<br>
+=C2=A0 =C2=A0Ensure that &lt;xref linkend=3D&quot;guc-effective-wal-lev<wb=
r>el&quot;/&gt; is at least replica<br>
+=C2=A0 =C2=A0(this is the default).<br>
=C2=A0&lt;programlisting&gt;<br>
-wal_level =3D logical<br>
+SHOW effective_wal_level;<br>
=C2=A0&lt;/programlisting&gt;<br>
-=C2=A0 =C2=A0The other required settings have default values that are suff=
icient for a<br>
+=C2=A0 =C2=A0The other required settings also have default values that are=
 sufficient for a<br>
=C2=A0 =C2=A0 basic setup.<br>
=C2=A0 =C2=A0&lt;/para&gt;<br>
```<br>
<br>
I think wal_level should be at least =E2=80=9Clogical=E2=80=9D. I don=E2=80=
=99t get why did you change to =E2=80=9Creplica=E2=80=9D? It=E2=80=99s clea=
r that we still need =E2=80=9Clogical=E2=80=9D to support logical replicati=
on.</blockquote><div><br></div><div>A minimum setting of replica is automat=
ically interpreted (i.e., effective WAL level) as logical when necessary so=
 the default setting of replica doesn=E2=80=99t need to be changed anymore.=
=C2=A0 Seeing replica in effective WAL level means no logical replication h=
as been setup and the dba hasn=E2=80=99t reduced the system to minimal.=C2=
=A0 If one sees logical there, that works too.</div><div><br></div><blockqu=
ote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc s=
olid;padding-left:1ex">
<br>
2<br>
```<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 &lt;literal&gt;replica&lt;/literal&gt;, which =
writes enough data to support<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 WAL archiving (see &lt;xref linkend=3D&quot;co=
ntinuous-archiving&quot;<wbr>/&gt;) and<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 physical replication (see &lt;xref linkend=3D&=
quot;streaming-replication<wbr>&quot;/&gt;)<br>
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 Running read-only queries on a standby server.=
 Below that is &lt;literal&gt;minimal&lt;/literal&gt;,<br>
```<br>
<br>
Here, =E2=80=9CRunning read-only =E2=80=A6=E2=80=9D sentence looks not smoo=
th, and there is not a period for the last sentence before =E2=80=9CRunning=
&quot;. The old wording was =E2=80=9Cincluding running read-only =E2=80=A6.=
=E2=80=9D.<br>
</blockquote><div><br></div><div>Yeah, I still stand by the whole of it but=
 need to do another pass.</div><div><br></div><div>I do get that there like=
ly wasn=E2=80=99t any ambiguity - even presented replica, minimal, logical =
- as to which was highest/middle/lower and being explicit here maybe seems =
overly verbose.</div><div><br></div><div>Also, I added a qualifier regardin=
g =E2=80=9Cprimary servers=E2=80=9D but am now unsure why.=C2=A0 Kinda conc=
erned about logical where publisher and subscriber are not mutually exclusi=
ve.</div><div><br></div><div><br></div>

--00000000000003a2a2064eea3fa1--