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

From: Florents Tselai <[email-masked]>
Date: Fri, 6 Feb 2026 17:36:34 +0200

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.

---

From: Andreas Karlsson <[email-masked]>
Date: Fri, 6 Feb 2026 22:03:15 +0100

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.

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

---

From: Masahiko Sawada <[email-masked]>
Date: Tue, 3 Mar 2026 14:23:45 -0800

On Fri, Feb 6, 2026 at 7:37 AM Florents Tselai
<[email-masked]> wrote:
>
> Twice this week I've encountered users confusing wal_level=logical with the actual setup of Logical Replication.
> 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

---

From: Florents Tselai <[email-masked]>
Date: Wed, 4 Mar 2026 13:34:42 +0200

On Wed, Mar 4, 2026 at 11:21 AM Chao Li <[email-masked]> wrote:

>
>
> > On Mar 4, 2026, at 06:23, Masahiko Sawada <[email-masked]> wrote:
> >
> 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 :)

---

From: "David G. Johnston" <[email-masked]>
Date: Wed, 4 Mar 2026 09:00:37 -0700

On Wed, Mar 4, 2026 at 7:11 AM Euler Taveira <[email-masked]> 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:

https://www.postgresql.org/message-id/CAKFQuwY=WLF0OH8JE5T8S=[email-masked]

David J.

---

From: Chao Li <[email-masked]>
Date: Thu, 5 Mar 2026 10:20:22 +0800

> On Mar 4, 2026, at 22:11, Euler Taveira <[email-masked]> wrote:
> 
> On Wed, Mar 4, 2026, at 8:34 AM, Florents Tselai wrote:
>> 
>> +        <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 in the 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 mention logical replication in the first place, and to not lose the info, mention “logical decoding” in the second place.

> I don't think such note should be added. If the DBA doesn't know how to setup

Agreed.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/