Обсуждение: doc: add note that wal_level=logical doesn't set up logical replication in itself
doc: add note that wal_level=logical doesn't set up logical replication in itself
От
Florents Tselai
Дата:
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.
Вложения
Re: doc: add note that wal_level=logical doesn't set up logical replication in itself
От
Andreas Karlsson
Дата:
On 2/6/26 4:36 PM, Florents Tselai 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. With the automatic change of effective WAL level which will be added in PostgreSQL 19 I think that addition will just move the confusion to another thing. If we want this note I think we need to clarify that replica is enough since that can be automatically increased to logical when necessary. Andreas
Re: doc: add note that wal_level=logical doesn't set up logical replication in itself
От
Masahiko Sawada
Дата:
On Fri, Feb 6, 2026 at 7:37 AM Florents Tselai
<florents.tselai@gmail.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
> On Mar 4, 2026, at 06:23, Masahiko Sawada <sawada.mshk@gmail.com> wrote: > > On Fri, Feb 6, 2026 at 7:37 AM Florents Tselai > <florents.tselai@gmail.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 streamingreplication 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. ``` Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
Re: doc: add note that wal_level=logical doesn't set up logical replication in itself
От
Florents Tselai
Дата:
On Wed, Mar 4, 2026 at 11:21 AM Chao Li <li.evan.chao@gmail.com> wrote:
> On Mar 4, 2026, at 06:23, Masahiko Sawada <sawada.mshk@gmail.com> wrote:
>
> On Fri, Feb 6, 2026 at 7:37 AM Florents Tselai
> <florents.tselai@gmail.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 :)
Вложения
Re: doc: add note that wal_level=logical doesn't set up logical replication in itself
От
"Euler Taveira"
Дата:
On Wed, Mar 4, 2026, at 8:34 AM, Florents Tselai wrote: > > + <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. > I'm not opposed to this idea. However, I would like to point out that 1) "replication" is mentioned for _replica_ which can introduce some confusion if we add "logical replication". Maybe it is a good idea to change the sentence below from "replication" to "physical replication". > The default value is replica, which writes enough data to support WAL > archiving and replication 2) There is no link to the sentence above. If you add a link to the logical replication section, I would suggest to add a link to the other cases (WAL archiving, physical replication) too. 3) If we are using "logical replication", should we mention "logical decoding"? The Logical Replication chapter mentions the use of logical decoding in the Architecture section. > > Something like: > Note that setting this parameter only enables the required WAL format; > it does not configure logical replication by itself. > I don't think such note should be added. If the DBA doesn't know how to setup logical replication, it should read the Logical Replication chapter. -- Euler Taveira EDB https://www.enterprisedb.com/
Re: doc: add note that wal_level=logical doesn't set up logical replication in itself
От
"David G. Johnston"
Дата:
On Wed, Mar 4, 2026 at 7:11 AM Euler Taveira <euler@eulerto.com> wrote:
>
> Something like:
> Note that setting this parameter only enables the required WAL format;
> it does not configure logical replication by itself.
>
I don't think such note should be added. If the DBA doesn't know how to setup
logical replication, it should read the Logical Replication chapter.
Yeah, I don't think this change is directly warranted. But in trying to figure out what we can do to improve matters I find that the documentation here has some room to improve that may indeed reduce confusion and be more informative than the proposed single line addition. In particular, now that we have effective_wal_level it is unclear why people would even be here changing wal_level in the first place. The quick start guide to logical replication is at least partially at fault in that regard.
Since the suggestion made here don't directly apply to the subject of this email thread, and I've some other suggestions as well, I've started a new thread here:
David J.
> On Mar 4, 2026, at 22:11, Euler Taveira <euler@eulerto.com> wrote: > > On Wed, Mar 4, 2026, at 8:34 AM, Florents Tselai wrote: >> >> + <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. >> > > I'm not opposed to this idea. However, I would like to point out that > > 1) "replication" is mentioned for _replica_ which can introduce some confusion > if we add "logical replication". Maybe it is a good idea to change the sentence > below from "replication" to "physical replication". > >> The default value is replica, which writes enough data to support WAL >> archiving and replication I agree with the point. But I think “streaming replication” is more common: “to support WAL archiving and streaming replication”. > > 2) There is no link to the sentence above. If you add a link to the logical > replication section, I would suggest to add a link to the other cases (WAL > archiving, physical replication) too. > I have no objection on updating other docs, but I don’t consider that is a must for the current patch. As Tom mentioned inthe other thread, there have been already a lot of inconsistencies, we cannot expect all docs written from a single pen. > 3) If we are using "logical replication", should we mention "logical decoding"? > The Logical Replication chapter mentions the use of logical decoding in the > Architecture section. > IMO, we should. Because the option actually enables “logical decoding” that is required by logical replication. So, we mentionlogical replication in the first place, and to not lose the info, mention “logical decoding” in the second place. >> >> Something like: >> Note that setting this parameter only enables the required WAL format; >> it does not configure logical replication by itself. >> > > I don't think such note should be added. If the DBA doesn't know how to setup > logical replication, it should read the Logical Replication chapter. > Agreed. Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
At 2026-03-04 22:11:16, "Euler Taveira" <euler@eulerto.com> wrote: >On Wed, Mar 4, 2026, at 8:34 AM, Florents Tselai wrote: >> >> + <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. >> > >I'm not opposed to this idea. However, I would like to point out that > >1) "replication" is mentioned for _replica_ which can introduce some confusion >if we add "logical replication". Maybe it is a good idea to change the sentence >below from "replication" to "physical replication". > >> The default value is replica, which writes enough data to support WAL >> archiving and replication > >2) There is no link to the sentence above. If you add a link to the logical >replication section, I would suggest to add a link to the other cases (WAL >archiving, physical replication) too. > >3) If we are using "logical replication", should we mention "logical decoding"? >The Logical Replication chapter mentions the use of logical decoding in the >Architecture section. > >> >> Something like: >> Note that setting this parameter only enables the required WAL format; >> it does not configure logical replication by itself. >> > >I don't think such note should be added. If the DBA doesn't know how to setup >logical replication, it should read the Logical Replication chapter. > > >-- >Euler Taveira >EDB https://www.enterprisedb.com/I fully agree with the points you've raised. I hope the author incorporates them.---Best regards,jinbinge