Re: doc: add note that wal_level=logical doesn't set up logical replication in itself

On Wed, Mar 4, 2026 at 11:21 AM Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com> wrote:

>
>
> > On Mar 4, 2026, at 06:23, Masahiko Sawada <sawada(dot)mshk(at)gmail(dot)com> wrote:
> >
> > On Fri, Feb 6, 2026 at 7:37 AM Florents Tselai
> > <florents(dot)tselai(at)gmail(dot)com> wrote:
> >>
> >> Twice this week I've encountered users confusing wal_level=logical with
> the actual setup of Logical Replication.
> >> Since users often land directly on the config.html page via search
> engines,
> >> they see the setting and assume enabling it is all that is required for
> replication to work.
> >> I think adding a clarification note here will prevent this (not so
> uncommon) misunderstanding.
> >
> > + <note>
> > + <para>
> > + Setting <literal>wal_level=logical</literal> enables logical
> decoding.
> > + It is a prerequisite for logical replication, but by itself
> > + does not configure logical replication; see <xref
> > linkend="logical-replication"/>.
> > + </para>
> > + </note>
> >
> > While I agree that it would be a good idea to mention logical
> > replication in the description of wal_level, the proposed change seems
> > not clear to me (specifically, what exactly means by "configure
> > logical replication"?). Given that we already mention logical decoding
> > in the description,
> >
> > Finally, logical adds information necessary to support logical decoding.
> >
> > How about adding logical replication with its link here? For example,
> >
> > diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
> > index f670e2d4c31..64672e559fc 100644
> > --- a/doc/src/sgml/config.sgml
> > +++ b/doc/src/sgml/config.sgml
> > @@ -3079,8 +3079,9 @@ include_dir 'conf.d'
> > logging except the information required to recover from a crash
> or
> > immediate shutdown. Finally,
> > <literal>logical</literal> adds information necessary to
> > support logical
> > - decoding. Each level includes the information logged at all
> lower
> > - levels. This parameter can only be set at server start.
> > + decoding and <link linkend="logical-replication">logical
> > replication</link>.
> > + Each level includes the information logged at all lower
> > levels. This parameter
> > + can only be set at server start.
> > </para>
> > <para>
> > The <literal>minimal</literal> level generates the least WAL
> >
> > While it's technically enough to mention only logical decoding as
> > logical replication is built on top of logical decoding, it's not
> > obvious for users. Explicitly adding the link to logical replication
> > might help users not to be confused.
> >
> > Feedback is very welcome.
> >
> > Regards,
> >
> > --
> > Masahiko Sawada
> > Amazon Web Services: https://aws.amazon.com
> >
> >
>
> As this is user documentation, I tend to think about it from a user's
> perspective. Many users think in terms of streaming replication and logical
> replication. They set this option to logical mainly because they want to
> use logical replication, while they might not necessarily care about or
> understand what logical decoding is.
>
> In my opinion, it might be better to mention what users care about first,
> something like:
> ```
> Finally, <literal>logical</literal> adds information necessary to support
> <link linkend="logical-replication">logical replication</link>, which
> relies on logical decoding. Each level includes the information logged
> at all lower levels.
> ```
>

Thank you both for your comments.
Indeed, user perspective is the thing here.
I agree about putting this into the para instead of note,
and I'm personally happy with this (attached)

+ <literal>logical</literal> adds information necessary to support
+ <link linkend="logical-replication">logical replication</link>,
which
+ relies on logical decoding. Each level includes the information
logged
+ at all lower levels.

Having said that, I still believe it's important to underline that this
config parameter
is not the "turn logical replication on" switch that many users expect.
Explicitly stating this will save DBAs a few keystrokes of explaining the
difference!

Something like:
Note that setting this parameter only enables the required WAL format; it
does not configure logical replication by itself.

I'll leave this up to Masahiko to add it if he wants :)