doc: Improve wal_level and effective_wal_level GUC around logical replication

On Tuesday, April 7, 2026, Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com> wrote:
>
> > On Mar 4, 2026, at 23:55, David G. Johnston <david(dot)g(dot)johnston(at)gmail(dot)com>
> wrote:
> >
> > Hi,
> >
> > 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 other
> 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="guc-effective-wal-level"/> is at least
> replica
> + (this is the default).
> <programlisting>
> -wal_level = 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 “logical”. I don’t get why did you
> change to “replica”? It’s clear that we still need “logical” 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’t need to be changed anymore. Seeing replica in effective WAL level
means no logical replication has been setup and the dba hasn’t reduced 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="continuous-archiving"/>) and
> + physical replication (see <xref linkend="streaming-replication
> "/>)
> + Running read-only queries on a standby server. Below that is
> <literal>minimal</literal>,
> ```
>
> Here, “Running read-only …” sentence looks not smooth, and there is not a
> period for the last sentence before “Running". The old wording was
> “including running read-only ….”.
>

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

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

Also, I added a qualifier regarding “primary servers” but am now unsure
why. Kinda concerned about logical where publisher and subscriber are not
mutually exclusive.