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

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

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 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.
```

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

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 :)

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/

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:

/messages/by-id/CAKFQuwY=WLF0OH8JE5T8S=aj0LBydiSn02fkRE73Sm_KSLRqJQ@mail.gmail.com

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 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.

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