Horton
Menu

Thread

  1. doc: Improve wal_level and effective_wal_level GUC around logical replication

    David G. Johnston <david.g.johnston@gmail.com> — 2026-03-04T15:55:13Z

    Hi,

In evaluating the proposed change to wal_level docs in [1] I found it to be
undesirable, but the discussion and my own review discovered some other
changes that should be considered.

Since effective_wal_level now exists, Logical Replication Getting Started
needs to be updated.
Add links to the main topics that the different levels apply to.
Be explicit about the ordering of minimal, replica, and logical.
Move the behavior of effective_wal_level to the GUC for it, leaving behind
just the pointer that wal_level is now just a "minimum".

David J.

[1]
https://www.postgresql.org/message-id/CA%2Bv5N42vKtY17653eBHFx%2BCw06E2fSmPrXmX2qKYG23%3D4Ycd7A%40mail.gmail.com

  2. Re: doc: Improve wal_level and effective_wal_level GUC around logical replication

    Andreas Karlsson <andreas@proxel.se> — 2026-04-07T21:59:24Z

    On 3/4/26 4:55 PM, David G. Johnston wrote:
> In evaluating the proposed change to wal_level docs in [1] I found it to 
> be undesirable, but the discussion and my own review discovered some 
> other changes that should be considered.

While I am not happy with the text before I am not sure your changes 
here really make it much better, just different, hmm.

> Since effective_wal_level now exists, Logical Replication Getting 
> Started needs to be updated.
> Add links to the main topics that the different levels apply to.
> Be explicit about the ordering of minimal, replica, and logical.
> Move the behavior of effective_wal_level to the GUC for it, leaving 
> behind just the pointer that wal_level is now just a "minimum".
Shouldn't it be:

"Ensure that <xref linkend="guc-wal-level"/> is at least replica"

and

"wal_level = replica"

as the logical replication slot may be created later?

-- 
Andreas Karlsson
Percona

  3. Re: doc: Improve wal_level and effective_wal_level GUC around logical replication

    Chao Li <li.evan.chao@gmail.com> — 2026-04-08T02:40:10Z

    
> On Mar 4, 2026, at 23:55, David G. Johnston <david.g.johnston@gmail.com> wrote:
> 
> Hi,
> 
> In evaluating the proposed change to wal_level docs in [1] I found it to be undesirable, but the discussion and my own review discovered some other changes that should be considered.
> 
> Since effective_wal_level now exists, Logical Replication Getting Started needs to be updated.
> Add links to the main topics that the different levels apply to.
> Be explicit about the ordering of minimal, replica, and logical.
> Move the behavior of effective_wal_level to the GUC for it, leaving behind just the pointer that wal_level is now just a "minimum".
> 
> David J.
> 
> [1] https://www.postgresql.org/message-id/CA%2Bv5N42vKtY17653eBHFx%2BCw06E2fSmPrXmX2qKYG23%3D4Ycd7A%40mail.gmail.com
> <v1-0001-doc-Add-some-clarity-around-wal_level.patch>


A few comments:

1
```
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -3508,11 +3508,12 @@ pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile
   <title>Quick Setup</title>
 
   <para>
-   First set the configuration options in <filename>postgresql.conf</filename>:
+   Ensure that <xref linkend="guc-effective-wal-level"/> is at least replica
+   (this is the default).
 <programlisting>
-wal_level = logical
+SHOW effective_wal_level;
 </programlisting>
-   The other required settings have default values that are sufficient for a
+   The other required settings also have default values that are sufficient for a
    basic setup.
   </para>
```

I think wal_level should be at least “logical”. I don’t get why did you change to “replica”? It’s clear that we still need “logical” to support logical replication.

2
```
+        <literal>replica</literal>, which writes enough data to support
+        WAL archiving (see <xref linkend="continuous-archiving"/>) and
+        physical replication (see <xref linkend="streaming-replication"/>)
+        Running read-only queries on a standby server. Below that is <literal>minimal</literal>,
```

Here, “Running read-only …” sentence looks not smooth, and there is not a period for the last sentence before “Running". The old wording was “including running read-only ….”.

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

  4. doc: Improve wal_level and effective_wal_level GUC around logical replication

    David G. Johnston <david.g.johnston@gmail.com> — 2026-04-08T03:10:45Z

    On Tuesday, April 7, 2026, Chao Li <li.evan.chao@gmail.com> wrote:
>
> > On Mar 4, 2026, at 23:55, David G. Johnston <david.g.johnston@gmail.com>
> wrote:
> >
> > Hi,
> >
> > In evaluating the proposed change to wal_level docs in [1] I found it to
> be undesirable, but the discussion and my own review discovered some other
> changes that should be considered.
> >
> > Since effective_wal_level now exists, Logical Replication Getting
> Started needs to be updated.
> > Add links to the main topics that the different levels apply to.
> > Be explicit about the ordering of minimal, replica, and logical.
> > Move the behavior of effective_wal_level to the GUC for it, leaving
> behind just the pointer that wal_level is now just a "minimum".
> >
> > David J.
> >
> > [1] https://www.postgresql.org/message-id/CA%2Bv5N42vKtY17653eBH
> Fx%2BCw06E2fSmPrXmX2qKYG23%3D4Ycd7A%40mail.gmail.com
> > <v1-0001-doc-Add-some-clarity-around-wal_level.patch>
>
>
> A few comments:
>
> 1
> ```
> --- a/doc/src/sgml/logical-replication.sgml
> +++ b/doc/src/sgml/logical-replication.sgml
> @@ -3508,11 +3508,12 @@ pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l
> logfile
>    <title>Quick Setup</title>
>
>    <para>
> -   First set the configuration options in <filename>postgresql.conf</fil
> ename>:
> +   Ensure that <xref linkend="guc-effective-wal-level"/> is at least
> replica
> +   (this is the default).
>  <programlisting>
> -wal_level = logical
> +SHOW effective_wal_level;
>  </programlisting>
> -   The other required settings have default values that are sufficient
> for a
> +   The other required settings also have default values that are
> sufficient for a
>     basic setup.
>    </para>
> ```
>
> I think wal_level should be at least “logical”. I don’t get why did you
> change to “replica”? It’s clear that we still need “logical” to support
> logical replication.


A minimum setting of replica is automatically interpreted (i.e., effective
WAL level) as logical when necessary so the default setting of replica
doesn’t need to be changed anymore.  Seeing replica in effective WAL level
means no logical replication has been setup and the dba hasn’t reduced the
system to minimal.  If one sees logical there, that works too.


> 2
> ```
> +        <literal>replica</literal>, which writes enough data to support
> +        WAL archiving (see <xref linkend="continuous-archiving"/>) and
> +        physical replication (see <xref linkend="streaming-replication
> "/>)
> +        Running read-only queries on a standby server. Below that is
> <literal>minimal</literal>,
> ```
>
> Here, “Running read-only …” sentence looks not smooth, and there is not a
> period for the last sentence before “Running". The old wording was
> “including running read-only ….”.
>

Yeah, I still stand by the whole of it but need to do another pass.

I do get that there likely wasn’t any ambiguity - even presented replica,
minimal, logical - as to which was highest/middle/lower and being explicit
here maybe seems overly verbose.

Also, I added a qualifier regarding “primary servers” but am now unsure
why.  Kinda concerned about logical where publisher and subscriber are not
mutually exclusive.

  5. Re: doc: Improve wal_level and effective_wal_level GUC around logical replication

    David G. Johnston <david.g.johnston@gmail.com> — 2026-04-08T03:27:54Z

    On Tuesday, April 7, 2026, Andreas Karlsson <andreas@proxel.se> wrote:

>
> Since effective_wal_level now exists, Logical Replication Getting Started
>> needs to be updated.
>>
>> Shouldn't it be:
>
> "Ensure that <xref linkend="guc-wal-level"/> is at least replica"
>

Given “at least” it is immaterial whether one inspects wal_level or
effective_wal_level.  It seems more intuitive to tell someone to look at
the value that represents what the system presently is using, not the
defined minimum level.

David J.

  6. Re: doc: Improve wal_level and effective_wal_level GUC around logical replication

    shveta malik <shveta.malik@gmail.com> — 2026-04-08T03:59:59Z

    Few comments:

1)
+        Running read-only queries on a standby server.

Looks incomplete and disconnected from previous sentence.

2)
+        level used by the system.  Namely, whether replica has been promoted to
+        logical (minimal never promotes).

We shall replace replica, logical, minimal with below
<literal>replica</literal>
<literal>logical</literal>
<literal>minimal</literal>

Also shall we add 'wal_level'? Otherwise, 'replica' on its own could
be understood as a replica server:

Namely, whether wal_level replica has been promoted to ....

3)
+        The <xref linkend="guc-effective-wal-level"/> parameter
reports the actual
+        level used by the system.  Namely, whether replica has been promoted to
+        logical (minimal never promotes).
+        This parameter can only be set at server start.

"This" here is misleading. Does this refer to wal_level or effective_wal_level?

4)
Below that is <literal>minimal</literal>,

Shall we change "that" to <literal>replica</literal> to avoid any confusion?

thanks
Shveta

  7. Re: doc: Improve wal_level and effective_wal_level GUC around logical replication

    David G. Johnston <david.g.johnston@gmail.com> — 2026-04-08T04:28:18Z

    Thank you, and the others, for the reviews.

On Tuesday, April 7, 2026, shveta malik <shveta.malik@gmail.com> wrote:

> Few comments:
>
> 1)
> +        Running read-only queries on a standby server.
>
> Looks incomplete and disconnected from previous sentence.


Yeah, I missed that one.


>
> 2)
> +        level used by the system.  Namely, whether replica has been
> promoted to
> +        logical (minimal never promotes).
>
> We shall replace replica, logical, minimal with below
> <literal>replica</literal>
> <literal>logical</literal>
> <literal>minimal</literal>


Yeah, I need to do a markup pass too apparently.  Though I do question
whether we are being too rote about these.  In this sentence yes I use the
actual labels but it’s more about concept than talking about something
you’d literally type somewhere.  One doesn’t promote a literal, they
promote the operating mode of the server which is then reflected by the
change of a value.


>
> Also shall we add 'wal_level'? Otherwise, 'replica' on its own could
> be understood as a replica server:
>
> Namely, whether wal_level replica has been promoted to ....


>
The preceding sentence to which “namely” links talks about the levels.  But
I’ll give it a second look.  From my reply above, writing “WAL level has
been promoted to logical from replica”, is probably a better structure.


> 3)
> +        The <xref linkend="guc-effective-wal-level"/> parameter
> reports the actual
> +        level used by the system.  Namely, whether replica has been
> promoted to
> +        logical (minimal never promotes).
> +        This parameter can only be set at server start.
>
> "This" here is misleading. Does this refer to wal_level or
> effective_wal_level?


When talking about where/when a setting can specified, “this” always refers
to the setting being documented.  I’m doubtful of the need to reword things
so that some other setting being talked about doesn’t get confused
instead.  The fact that we say effective WAL level is basically a runtime
derived setting in the prior sentence reinforces this belief.  And we try
to keep this sentence consistently at the end of the description.  Maybe it
needs its own paragraph though?  I’ll consider that.


>
> 4)
> Below that is <literal>minimal</literal>,
>
> Shall we change "that" to <literal>replica</literal> to avoid any
> confusion?


I’m on the fence at the moment.  This entire section needs a relook anyway
and I’ll keep all these in mind.

David J.