Merge wal_level "archive" and "hot_standby" into new name "replica"

The distinction between "archive" and "hot_standby" existed only because
at the time "hot_standby" was added, there was some uncertainty about
stability.  This is now a long time ago.  We would like to move forward
with simplifying the replication configuration, but this distinction is
in the way, because a primary server cannot tell (without asking a
standby or predicting the future) which one of these would be the
appropriate level.

Pick a new name for the combined setting to make it clearer that it
covers all (non-logical) backup and replication uses.  The old values
are still accepted but are converted internally.

Reviewed-by: Michael Paquier <michael.paquier@gmail.com>
Reviewed-by: David Steele <david@pgmasters.net>

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 7413666382c1d228e63f99097299c6df96e727a1..9092cf8fe333bb3cd65a953cae91d9484bf4b0a8 100644 (file)
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -592,7 +592,7 @@ tar -cf backup.tar /usr/local/pgsql/data
 
    <para>
     To enable WAL archiving, set the <xref linkend="guc-wal-level">
-    configuration parameter to <literal>archive</> or higher,
+    configuration parameter to <literal>replica</> or higher,
     <xref linkend="guc-archive-mode"> to <literal>on</>,
     and specify the shell command to use in the <xref
     linkend="guc-archive-command"> configuration parameter.  In practice
@@ -1285,7 +1285,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
       If more flexibility in copying the backup files is needed, a lower
       level process can be used for standalone hot backups as well.
       To prepare for low level standalone hot backups, set <varname>wal_level</> to
-      <literal>archive</> or higher, <varname>archive_mode</> to
+      <literal>replica</> or higher, <varname>archive_mode</> to
       <literal>on</>, and set up an <varname>archive_command</> that performs
       archiving only when a <emphasis>switch file</> exists.  For example:
 <programlisting>

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 7695ec186e9217f439dc2d8ae380c8d32384ae81..d48a13f33a8bbd7c0c1c48ab4870506bc9dee00d 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -2029,9 +2029,9 @@ include_dir 'conf.d'
         <varname>wal_level</> determines how much information is written
         to the WAL. The default value is <literal>minimal</>, which writes
         only the information needed to recover from a crash or immediate
-        shutdown. <literal>archive</> adds logging required for WAL archiving;
-        <literal>hot_standby</> further adds information required to run
-        read-only queries on a standby server; and, finally
+        shutdown. <literal>replica</> adds logging required for WAL
+        archiving as well as information required to run
+        read-only queries on a standby server.  Finally,
         <literal>logical</> 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.
@@ -2049,30 +2049,24 @@ include_dir 'conf.d'
          transaction</member>
         </simplelist>
         But minimal WAL does not contain enough information to reconstruct the
-        data from a base backup and the WAL logs, so <literal>archive</> or
+        data from a base backup and the WAL logs, so <literal>replica</> or
         higher must be used to enable WAL archiving
         (<xref linkend="guc-archive-mode">) and streaming replication.
        </para>
-       <para>
-        In <literal>hot_standby</> level, the same information is logged as
-        with <literal>archive</>, plus information needed to reconstruct
-        the status of running transactions from the WAL. To enable read-only
-        queries on a standby server, <varname>wal_level</> must be set to
-        <literal>hot_standby</> or higher on the primary, and
-        <xref linkend="guc-hot-standby"> must be enabled in the standby. It is
-        thought that there is little measurable difference in performance
-        between using <literal>hot_standby</> and <literal>archive</> levels,
-        so feedback is welcome if any production impacts are noticeable.
-       </para>
        <para>
         In <literal>logical</> level, the same information is logged as
-        with <literal>hot_standby</>, plus information needed to allow
+        with <literal>replica</>, plus information needed to allow
         extracting logical change sets from the WAL. Using a level of
         <literal>logical</> will increase the WAL volume, particularly if many
         tables are configured for <literal>REPLICA IDENTITY FULL</literal> and
         many <command>UPDATE</> and <command>DELETE</> statements are
         executed.
        </para>
+       <para>
+        In releases prior to 9.6, this parameter also allowed the
+        values <literal>archive</literal> and <literal>hot_standby</literal>.
+        These are still accepted but mapped to <literal>replica</literal>.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -2784,7 +2778,7 @@ include_dir 'conf.d'
         higher than the maximum number of expected clients so disconnected
         clients can immediately reconnect.  This parameter can only
         be set at server start. <varname>wal_level</> must be set to
-        <literal>archive</> or higher to allow connections from standby
+        <literal>replica</> or higher to allow connections from standby
         servers.
        </para>
        </listitem>
@@ -2803,7 +2797,7 @@ include_dir 'conf.d'
          can support. The default is zero.  This parameter can only be set at
          server start.
          <varname>wal_level</varname> must be set
-         to <literal>archive</literal> or higher to allow replication slots to
+         to <literal>replica</literal> or higher to allow replication slots to
          be used. Setting it to a lower value than the number of currently
          existing replication slots will prevent the server from starting.
         </para>

diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index 6cb690c59aae48a9386e327824ccb6bf2da44bd6..19d613e3b1a1bd11936c1f8ec038cf29aca894b8 100644 (file)
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -1988,7 +1988,7 @@ LOG:  database system is ready to accept read only connections
     Consistency information is recorded once per checkpoint on the primary.
     It is not possible to enable hot standby when reading WAL
     written during a period when <varname>wal_level</> was not set to
-    <literal>hot_standby</> or <literal>logical</> on the primary.  Reaching
+    <literal>replica</> or <literal>logical</> on the primary.  Reaching
     a consistent state can also be delayed in the presence of both of these
     conditions:
 

diff --git a/doc/src/sgml/ref/alter_system.sgml b/doc/src/sgml/ref/alter_system.sgml
index f6a018f341bc3bb553d02abaca66ce9ea87b5ed0..00fd8d7c32c499f70f30de80b734b4b044c6847c 100644 (file)
--- a/doc/src/sgml/ref/alter_system.sgml
+++ b/doc/src/sgml/ref/alter_system.sgml
@@ -108,7 +108,7 @@ ALTER SYSTEM RESET ALL
   <para>
    Set the <literal>wal_level</>:
 <programlisting>
-ALTER SYSTEM SET wal_level = hot_standby;
+ALTER SYSTEM SET wal_level = replica;
 </programlisting>
   </para>
 

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index eb113c2629157e73c284a302a3be037d0231505e..b99e546a7e03c329b8d290575a1694f284947493 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -477,7 +477,7 @@ pg_upgrade.exe
 
       <para>
        In the new master cluster, change <varname>wal_level</> to
-       <literal>hot_standby</> in the <filename>postgresql.conf</> file
+       <literal>replica</> in the <filename>postgresql.conf</> file
        and then start and stop the cluster.
       </para>
      </step>

diff --git a/src/backend/access/rmgrdesc/xlogdesc.c b/src/backend/access/rmgrdesc/xlogdesc.c
index 2dcbfbda3727236ebd7de34910518e899218ea1e..022bd44eff27ae80a87a34feb3a23ff4b2754353 100644 (file)
--- a/src/backend/access/rmgrdesc/xlogdesc.c
+++ b/src/backend/access/rmgrdesc/xlogdesc.c
@@ -25,8 +25,9 @@
  */
 const struct config_enum_entry wal_level_options[] = {
        {"minimal", WAL_LEVEL_MINIMAL, false},
-       {"archive", WAL_LEVEL_ARCHIVE, false},
-       {"hot_standby", WAL_LEVEL_HOT_STANDBY, false},
+       {"replica", WAL_LEVEL_REPLICA, false},
+       {"archive", WAL_LEVEL_REPLICA, true},  /* deprecated */
+       {"hot_standby", WAL_LEVEL_REPLICA, true},  /* deprecated */
        {"logical", WAL_LEVEL_LOGICAL, false},
        {NULL, 0, false}
 };

diff --git a/src/backend/access/transam/xact.c b/src/backend/access/transam/xact.c
index 8a2cd452056dfd5bd8e4d04f835a27a5a4f6acb4..89a14b4cbe4bdd4583342a9ee2f1faea14ae3d4a 100644 (file)
--- a/src/backend/access/transam/xact.c
+++ b/src/backend/access/transam/xact.c
@@ -1254,7 +1254,7 @@ RecordTransactionCommit(void)
         * this case, but we don't currently try to do that.  It would certainly
         * cause problems at least in Hot Standby mode, where the
         * KnownAssignedXids machinery requires tracking every XID assignment.  It
-        * might be OK to skip it only when wal_level < hot_standby, but for now
+        * might be OK to skip it only when wal_level < replica, but for now
         * we don't.)
         *
         * However, if we're doing cleanup of any non-temp rels or committing any

diff --git a/src/backend/access/transam/xlog.c b/src/backend/access/transam/xlog.c
index f70bb49012eb71440bce845c9c3cf5482c5529c8..b119a47e4e03ea2bd3483224d006c7d1711eaf22 100644 (file)
--- a/src/backend/access/transam/xlog.c
+++ b/src/backend/access/transam/xlog.c
@@ -5866,7 +5866,7 @@ static void
 CheckRequiredParameterValues(void)
 {
        /*
-        * For archive recovery, the WAL must be generated with at least 'archive'
+        * For archive recovery, the WAL must be generated with at least 'replica'
         * wal_level.
         */
        if (ArchiveRecoveryRequested && ControlFile->wal_level == WAL_LEVEL_MINIMAL)
@@ -5877,15 +5877,15 @@ CheckRequiredParameterValues(void)
        }
 
        /*
-        * For Hot Standby, the WAL must be generated with 'hot_standby' mode, and
+        * For Hot Standby, the WAL must be generated with 'replica' mode, and
         * we must have at least as many backend slots as the primary.
         */
        if (ArchiveRecoveryRequested && EnableHotStandby)
        {
-               if (ControlFile->wal_level < WAL_LEVEL_HOT_STANDBY)
+               if (ControlFile->wal_level < WAL_LEVEL_REPLICA)
                        ereport(ERROR,
-                                       (errmsg("hot standby is not possible because wal_level was not set to \"hot_standby\" or higher on the master server"),
-                                        errhint("Either set wal_level to \"hot_standby\" on the master, or turn off hot_standby here.")));
+                                       (errmsg("hot standby is not possible because wal_level was not set to \"replica\" or higher on the master server"),
+                                        errhint("Either set wal_level to \"replica\" on the master, or turn off hot_standby here.")));
 
                /* We ignore autovacuum_max_workers when we make this test. */
                RecoveryRequiresIntParameter("max_connections",
@@ -9459,10 +9459,8 @@ xlog_redo(XLogReaderState *record)
                /*
                 * Update minRecoveryPoint to ensure that if recovery is aborted, we
                 * recover back up to this point before allowing hot standby again.
-                * This is particularly important if wal_level was set to 'archive'
-                * before, and is now 'hot_standby', to ensure you don't run queries
-                * against the WAL preceding the wal_level change. Same applies to
-                * decreasing max_* settings.
+                * This is important if the max_* settings are decreased, to ensure
+                * you don't run queries against the WAL preceding the change.
                 */
                minRecoveryPoint = ControlFile->minRecoveryPoint;
                minRecoveryPointTLI = ControlFile->minRecoveryPointTLI;
@@ -9793,7 +9791,7 @@ do_pg_start_backup(const char *backupidstr, bool fast, TimeLineID *starttli_p,
                ereport(ERROR,
                                (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
                          errmsg("WAL level not sufficient for making an online backup"),
-                                errhint("wal_level must be set to \"archive\", \"hot_standby\", or \"logical\" at server start.")));
+                                errhint("wal_level must be set to \"replica\" or \"logical\" at server start.")));
 
        if (strlen(backupidstr) > MAXPGPATH)
                ereport(ERROR,
@@ -10264,7 +10262,7 @@ do_pg_stop_backup(char *labelfile, bool waitforarchive, TimeLineID *stoptli_p)
                ereport(ERROR,
                                (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
                          errmsg("WAL level not sufficient for making an online backup"),
-                                errhint("wal_level must be set to \"archive\", \"hot_standby\", or \"logical\" at server start.")));
+                                errhint("wal_level must be set to \"replica\" or \"logical\" at server start.")));
 
        /*
         * OK to update backup counters and forcePageWrites

diff --git a/src/backend/access/transam/xlogfuncs.c b/src/backend/access/transam/xlogfuncs.c
index 31cbb01ce47122fc179cff6814e6c5ec69f59871..9ec6b2ae4f1be904c8c63312a0dc2d0f7ba4701c 100644 (file)
--- a/src/backend/access/transam/xlogfuncs.c
+++ b/src/backend/access/transam/xlogfuncs.c
@@ -154,7 +154,7 @@ pg_create_restore_point(PG_FUNCTION_ARGS)
                ereport(ERROR,
                                (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
                         errmsg("WAL level not sufficient for creating a restore point"),
-                                errhint("wal_level must be set to \"archive\", \"hot_standby\", or \"logical\" at server start.")));
+                                errhint("wal_level must be set to \"replica\" or \"logical\" at server start.")));
 
        restore_name_str = text_to_cstring(restore_name);
 

diff --git a/src/backend/postmaster/postmaster.c b/src/backend/postmaster/postmaster.c
index b16fc28a27dd251f915771df6cb11975b48dd87d..6cf51e1b64dbd3977fe8e8adf2c381ce22442465 100644 (file)
--- a/src/backend/postmaster/postmaster.c
+++ b/src/backend/postmaster/postmaster.c
@@ -858,7 +858,7 @@ PostmasterMain(int argc, char *argv[])
                                (errmsg("WAL archival cannot be enabled when wal_level is \"minimal\"")));
        if (max_wal_senders > 0 && wal_level == WAL_LEVEL_MINIMAL)
                ereport(ERROR,
-                               (errmsg("WAL streaming (max_wal_senders > 0) requires wal_level \"archive\", \"hot_standby\", or \"logical\"")));
+                               (errmsg("WAL streaming (max_wal_senders > 0) requires wal_level \"replica\" or \"logical\"")));
 
        /*
         * Other one-time internal sanity checks can go here, if they are fast.

diff --git a/src/backend/replication/slot.c b/src/backend/replication/slot.c
index ead221d3c759ef4525c8ec082162dcc58882d7ac..c13be753ea95657f84455844f8f8cb1eabf3d8ce 100644 (file)
--- a/src/backend/replication/slot.c
+++ b/src/backend/replication/slot.c
@@ -760,7 +760,7 @@ CheckSlotRequirements(void)
                                (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
                                 (errmsg("replication slots can only be used if max_replication_slots > 0"))));
 
-       if (wal_level < WAL_LEVEL_ARCHIVE)
+       if (wal_level < WAL_LEVEL_REPLICA)
                ereport(ERROR,
                                (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
                                 errmsg("replication slots can only be used if wal_level >= archive")));

diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample
index 773b4e8a4fce306427aa80fc1147d45d9b256799..5536012e05053b8167056b1be5678c53d13a2a27 100644 (file)
--- a/src/backend/utils/misc/postgresql.conf.sample
+++ b/src/backend/utils/misc/postgresql.conf.sample
@@ -173,7 +173,7 @@
 
 # - Settings -
 
-#wal_level = minimal                   # minimal, archive, hot_standby, or logical
+#wal_level = minimal                   # minimal, replica, or logical
                                        # (change requires restart)
 #fsync = on                            # turns forced synchronization on or off
 #synchronous_commit = on               # synchronization level;

diff --git a/src/bin/pg_basebackup/t/010_pg_basebackup.pl b/src/bin/pg_basebackup/t/010_pg_basebackup.pl
index e097619310f7eaed27961f01ed59910c30be05ce..f4769bf535d725118681b9a9644f3c02ceba92dd 100644 (file)
--- a/src/bin/pg_basebackup/t/010_pg_basebackup.pl
+++ b/src/bin/pg_basebackup/t/010_pg_basebackup.pl
@@ -43,7 +43,7 @@ $node->command_fails(
 open CONF, ">>$pgdata/postgresql.conf";
 print CONF "max_replication_slots = 10\n";
 print CONF "max_wal_senders = 10\n";
-print CONF "wal_level = archive\n";
+print CONF "wal_level = replica\n";
 close CONF;
 $node->restart;
 

diff --git a/src/bin/pg_controldata/pg_controldata.c b/src/bin/pg_controldata/pg_controldata.c
index fdf7c7de9b66883f77dc229c8dc6894f17869239..96619a20769f835343cf2a77ecf32fcea40b9be6 100644 (file)
--- a/src/bin/pg_controldata/pg_controldata.c
+++ b/src/bin/pg_controldata/pg_controldata.c
@@ -73,10 +73,8 @@ wal_level_str(WalLevel wal_level)
        {
                case WAL_LEVEL_MINIMAL:
                        return "minimal";
-               case WAL_LEVEL_ARCHIVE:
-                       return "archive";
-               case WAL_LEVEL_HOT_STANDBY:
-                       return "hot_standby";
+               case WAL_LEVEL_REPLICA:
+                       return "replica";
                case WAL_LEVEL_LOGICAL:
                        return "logical";
        }

diff --git a/src/include/access/xlog.h b/src/include/access/xlog.h
index ecd30ce3ce219225bfb2725fa0d2c8fb14c5b3a6..74a139496e6cf61492bd11a154bd7b4da7508c2c 100644 (file)
--- a/src/include/access/xlog.h
+++ b/src/include/access/xlog.h
@@ -121,25 +121,24 @@ extern int        XLogArchiveMode;
 typedef enum WalLevel
 {
        WAL_LEVEL_MINIMAL = 0,
-       WAL_LEVEL_ARCHIVE,
-       WAL_LEVEL_HOT_STANDBY,
+       WAL_LEVEL_REPLICA,
        WAL_LEVEL_LOGICAL
 } WalLevel;
 extern int     wal_level;
 
 /* Is WAL archiving enabled (always or only while server is running normally)? */
 #define XLogArchivingActive() \
-       (XLogArchiveMode > ARCHIVE_MODE_OFF && wal_level >= WAL_LEVEL_ARCHIVE)
+       (AssertMacro(XLogArchiveMode == ARCHIVE_MODE_OFF || wal_level >= WAL_LEVEL_REPLICA), XLogArchiveMode > ARCHIVE_MODE_OFF)
 /* Is WAL archiving enabled always (even during recovery)? */
 #define XLogArchivingAlways() \
-       (XLogArchiveMode == ARCHIVE_MODE_ALWAYS && wal_level >= WAL_LEVEL_ARCHIVE)
+       (AssertMacro(XLogArchiveMode == ARCHIVE_MODE_OFF || wal_level >= WAL_LEVEL_REPLICA), XLogArchiveMode == ARCHIVE_MODE_ALWAYS)
 #define XLogArchiveCommandSet() (XLogArchiveCommand[0] != '\0')
 
 /*
  * Is WAL-logging necessary for archival or log-shipping, or can we skip
  * WAL-logging if we fsync() the data before committing instead?
  */
-#define XLogIsNeeded() (wal_level >= WAL_LEVEL_ARCHIVE)
+#define XLogIsNeeded() (wal_level >= WAL_LEVEL_REPLICA)
 
 /*
  * Is a full-page image needed for hint bit updates?
@@ -153,7 +152,7 @@ extern int  wal_level;
 #define XLogHintBitIsNeeded() (DataChecksumsEnabled() || wal_log_hints)
 
 /* Do we need to WAL-log information required only for Hot Standby and logical replication? */
-#define XLogStandbyInfoActive() (wal_level >= WAL_LEVEL_HOT_STANDBY)
+#define XLogStandbyInfoActive() (wal_level >= WAL_LEVEL_REPLICA)
 
 /* Do we need to WAL-log information required only for logical replication? */
 #define XLogLogicalInfoActive() (wal_level >= WAL_LEVEL_LOGICAL)

diff --git a/src/include/catalog/pg_control.h b/src/include/catalog/pg_control.h
index 86fbdce0e82544e139816a6c68ba6461de0082aa..7ba396df515ac33650f0ff203a8bd32236e693ad 100644 (file)
--- a/src/include/catalog/pg_control.h
+++ b/src/include/catalog/pg_control.h
@@ -54,7 +54,7 @@ typedef struct CheckPoint
        /*
         * Oldest XID still running. This is only needed to initialize hot standby
         * mode from an online checkpoint, so we only bother calculating this for
-        * online checkpoints and only when wal_level is hot_standby. Otherwise
+        * online checkpoints and only when wal_level is replica. Otherwise
         * it's set to InvalidTransactionId.
         */
        TransactionId oldestActiveXid;

diff --git a/src/test/perl/PostgresNode.pm b/src/test/perl/PostgresNode.pm
index 090d48c40673822178cca6a8201183886b4d53f9..1eedd19c8a89e1f37ec063d6dc17b2136f6c5bad 100644 (file)
--- a/src/test/perl/PostgresNode.pm
+++ b/src/test/perl/PostgresNode.pm
@@ -404,7 +404,7 @@ sub init
 
        if ($params{allows_streaming})
        {
-               print $conf "wal_level = hot_standby\n";
+               print $conf "wal_level = replica\n";
                print $conf "max_wal_senders = 5\n";
                print $conf "wal_keep_segments = 20\n";
                print $conf "max_wal_size = 128MB\n";