public inbox for [email protected]help / color / mirror / Atom feed
doc: Improve wal_level and effective_wal_level GUC around logical replication 7+ messages / 4 participants [nested] [flat]
* doc: Improve wal_level and effective_wal_level GUC around logical replication @ 2026-03-04 15:55 David G. Johnston <[email protected]> 2026-04-07 21:59 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication Andreas Karlsson <[email protected]> 2026-04-08 02:40 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication Chao Li <[email protected]> 0 siblings, 2 replies; 7+ messages in thread From: David G. Johnston @ 2026-03-04 15:55 UTC (permalink / raw) To: PostgreSQL Hackers <[email protected]> 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%40ma... Attachments: [text/x-patch] v1-0001-doc-Add-some-clarity-around-wal_level.patch (6.0K, 3-v1-0001-doc-Add-some-clarity-around-wal_level.patch) download | inline diff: From f4f229b4f16cfb674950e08f213dc64d854c980d Mon Sep 17 00:00:00 2001 From: "David G. Johnston" <[email protected]> Date: Wed, 4 Mar 2026 08:04:42 -0700 Subject: [PATCH v1] doc: Add some clarity around wal_level --- doc/src/sgml/config.sgml | 51 ++++++++++++--------------- doc/src/sgml/logical-replication.sgml | 7 ++-- 2 files changed, 27 insertions(+), 31 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index f670e2d4c31..406518aae63 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -3072,15 +3072,21 @@ include_dir 'conf.d' </term> <listitem> <para> - <varname>wal_level</varname> determines how much information is written to - the WAL. The default value is <literal>replica</literal>, which writes enough - data to support WAL archiving and replication, including running - read-only queries on a standby server. <literal>minimal</literal> removes all - 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. + <varname>wal_level</varname> determines the minimum amount of information + that is to be written to the WAL. The default, and middle, value is + <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>, + which removes all logging except the information required to recover from a crash or + immediate shutdown. Finally, above replica, is <literal>logical</literal>, + which adds information necessary to support logical decoding and + logical replication (see <xref linkend="logical-replication"/>). + Each level includes the information logged at all lower levels. + 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. </para> <para> The <literal>minimal</literal> level generates the least WAL @@ -3117,17 +3123,6 @@ include_dir 'conf.d' many <command>UPDATE</command> and <command>DELETE</command> statements are executed. </para> - <para> - It is important to note that when <varname>wal_level</varname> is set to - <literal>replica</literal>, the effective WAL level can automatically change - based on the presence of <link linkend="logicaldecoding-replication-slots"> - logical replication slots</link>. The system automatically increases the - effective WAL level to <literal>logical</literal> when creating the first - logical replication slot, and decreases it back to <literal>replica</literal> - when dropping or invalidating the last logical replication slot. The current - effective WAL level can be monitored through - <xref linkend="guc-effective-wal-level"/> parameter. - </para> <para> In releases prior to 9.6, this parameter also allowed the values <literal>archive</literal> and <literal>hot_standby</literal>. @@ -11945,17 +11940,17 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' system. This parameter shares the same set of values as <xref linkend="guc-wal-level"/>, but reflects the operational WAL level rather than the configured setting. For descriptions of - possible values, refer to the <varname>wal_level</varname> + possible values, refer to the <xref linkend="guc-wal-level"/> parameter documentation. </para> <para> - The effective WAL level can differ from the configured - <varname>wal_level</varname> in certain situations. For example, - when <varname>wal_level</varname> is set to <literal>replica</literal> - and the system has one or more logical replication slots, - <varname>effective_wal_level</varname> will show <literal>logical</literal> - to indicate that the system is maintaining WAL records at - <literal>logical</literal> level equivalent. + Presently, on primary servers, differences from <xref linkend="guc-wal-level"/> + only happen when <xref linkend="guc-wal-level"/> is set to <literal>replica</literal>. + Based on the presence of <link linkend="logicaldecoding-replication-slots"> + logical replication slots</link>, the system automatically increases the + effective WAL level to <literal>logical</literal> when creating the first + logical replication slot, and decreases it back to <literal>replica</literal> + when dropping or invalidating the last logical replication slot. </para> <para> On standby servers, <varname>effective_wal_level</varname> matches diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index 5028fe9af09..c709224de0a 100644 --- 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> -- 2.43.0 ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: doc: Improve wal_level and effective_wal_level GUC around logical replication 2026-03-04 15:55 doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> @ 2026-04-07 21:59 ` Andreas Karlsson <[email protected]> 2026-04-08 03:27 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> 1 sibling, 1 reply; 7+ messages in thread From: Andreas Karlsson @ 2026-04-07 21:59 UTC (permalink / raw) To: David G. Johnston <[email protected]>; PostgreSQL Hackers <[email protected]> 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 ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: doc: Improve wal_level and effective_wal_level GUC around logical replication 2026-03-04 15:55 doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> 2026-04-07 21:59 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication Andreas Karlsson <[email protected]> @ 2026-04-08 03:27 ` David G. Johnston <[email protected]> 2026-04-08 03:59 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication shveta malik <[email protected]> 0 siblings, 1 reply; 7+ messages in thread From: David G. Johnston @ 2026-04-08 03:27 UTC (permalink / raw) To: Andreas Karlsson <[email protected]>; +Cc: PostgreSQL Hackers <[email protected]> On Tuesday, April 7, 2026, Andreas Karlsson <[email protected]> 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. ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: doc: Improve wal_level and effective_wal_level GUC around logical replication 2026-03-04 15:55 doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> 2026-04-07 21:59 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication Andreas Karlsson <[email protected]> 2026-04-08 03:27 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> @ 2026-04-08 03:59 ` shveta malik <[email protected]> 2026-04-08 04:28 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> 0 siblings, 1 reply; 7+ messages in thread From: shveta malik @ 2026-04-08 03:59 UTC (permalink / raw) To: David G. Johnston <[email protected]>; +Cc: Andreas Karlsson <[email protected]>; PostgreSQL Hackers <[email protected]>; shveta malik <[email protected]> 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 ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: doc: Improve wal_level and effective_wal_level GUC around logical replication 2026-03-04 15:55 doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> 2026-04-07 21:59 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication Andreas Karlsson <[email protected]> 2026-04-08 03:27 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> 2026-04-08 03:59 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication shveta malik <[email protected]> @ 2026-04-08 04:28 ` David G. Johnston <[email protected]> 0 siblings, 0 replies; 7+ messages in thread From: David G. Johnston @ 2026-04-08 04:28 UTC (permalink / raw) To: shveta malik <[email protected]>; +Cc: Andreas Karlsson <[email protected]>; PostgreSQL Hackers <[email protected]> Thank you, and the others, for the reviews. On Tuesday, April 7, 2026, shveta malik <[email protected]> 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. ^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: doc: Improve wal_level and effective_wal_level GUC around logical replication 2026-03-04 15:55 doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> @ 2026-04-08 02:40 ` Chao Li <[email protected]> 2026-04-08 03:10 ` doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> 1 sibling, 1 reply; 7+ messages in thread From: Chao Li @ 2026-04-08 02:40 UTC (permalink / raw) To: David G. Johnston <[email protected]>; +Cc: PostgreSQL Hackers <[email protected]> > On Mar 4, 2026, at 23:55, David G. Johnston <[email protected]> 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%40ma... > <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/ ^ permalink raw reply [nested|flat] 7+ messages in thread
* doc: Improve wal_level and effective_wal_level GUC around logical replication 2026-03-04 15:55 doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> 2026-04-08 02:40 ` Re: doc: Improve wal_level and effective_wal_level GUC around logical replication Chao Li <[email protected]> @ 2026-04-08 03:10 ` David G. Johnston <[email protected]> 0 siblings, 0 replies; 7+ messages in thread From: David G. Johnston @ 2026-04-08 03:10 UTC (permalink / raw) To: Chao Li <[email protected]>; +Cc: PostgreSQL Hackers <[email protected]> On Tuesday, April 7, 2026, Chao Li <[email protected]> wrote: > > > On Mar 4, 2026, at 23:55, David G. Johnston <[email protected]> > 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. ^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2026-04-08 04:28 UTC | newest] Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-03-04 15:55 doc: Improve wal_level and effective_wal_level GUC around logical replication David G. Johnston <[email protected]> 2026-04-07 21:59 ` Andreas Karlsson <[email protected]> 2026-04-08 03:27 ` David G. Johnston <[email protected]> 2026-04-08 03:59 ` shveta malik <[email protected]> 2026-04-08 04:28 ` David G. Johnston <[email protected]> 2026-04-08 02:40 ` Chao Li <[email protected]> 2026-04-08 03:10 ` David G. Johnston <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox