On Wed, Mar 4, 2026 at 11:21 AM Chao Li <[email protected]> wrote:
> > > > On Mar 4, 2026, at 06:23, Masahiko Sawada <[email protected]> wrote: > > > > On Fri, Feb 6, 2026 at 7:37 AM Florents Tselai > > <[email protected]> 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 :)
wal-level-note.diff
Description: Binary data
