Re: doc: add note that wal_level=logical doesn't set up logical replication in itself - Mailing list pgsql-hackers

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