Remove exclusive backup mode

Exclusive-mode backups have been deprecated since 9.6 (when
non-exclusive backups were introduced) due to the issues
they can cause should the system crash while one is running and
generally because non-exclusive provides a much better interface.
Further, exclusive backup mode wasn't really being tested (nor was most
of the related code- like being able to log in just to stop an exclusive
backup and the bits of the state machine related to that) and having to
possibly deal with an exclusive backup and the backup_label file
existing during pg_basebackup, pg_rewind, etc, added other complexities
that we are better off without.

This patch removes the exclusive backup mode, the various special cases
for dealing with it, and greatly simplifies the online backup code and
documentation.

Authors: David Steele, Nathan Bossart
Reviewed-by: Chapman Flack
Discussion: https://postgr.es/m/ac7339ca-3718-3c93-929f-99e725d1172c@pgmasters.net
https://postgr.es/m/CAHg+QDfiM+WU61tF6=nPZocMZvHDzCK47Kneyb0ZRULYzV5sKQ@mail.gmail.com

Author: sfrost

doc/src/sgml/backup.sgml

@@ -25618,9 +25618,8 @@ LOG:  Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
     The functions shown in <xref
     linkend="functions-admin-backup-table"/> assist in making on-line backups.
     These functions cannot be executed during recovery (except
-    non-exclusive <function>pg_start_backup</function>,
-    non-exclusive <function>pg_stop_backup</function>,
-    <function>pg_is_in_backup</function>, <function>pg_backup_start_time</function>
+    <function>pg_backup_start</function>,
+    <function>pg_backup_stop</function>,
     and <function>pg_wal_lsn_diff</function>).
    </para>
 
@@ -25709,13 +25708,12 @@ LOG:  Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
-         <primary>pg_start_backup</primary>
+         <primary>pg_backup_start</primary>
         </indexterm>
-        <function>pg_start_backup</function> (
+        <function>pg_backup_start</function> (
           <parameter>label</parameter> <type>text</type>
           <optional>, <parameter>fast</parameter> <type>boolean</type>
-          <optional>, <parameter>exclusive</parameter> <type>boolean</type>
-          </optional></optional> )
+          </optional> )
         <returnvalue>pg_lsn</returnvalue>
        </para>
        <para>
@@ -25724,23 +25722,9 @@ LOG:  Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
         (Typically this would be the name under which the backup dump file
         will be stored.)
         If the optional second parameter is given as <literal>true</literal>,
-        it specifies executing <function>pg_start_backup</function> as quickly
+        it specifies executing <function>pg_backup_start</function> as quickly
         as possible.  This forces an immediate checkpoint which will cause a
         spike in I/O operations, slowing any concurrently executing queries.
-        The optional third parameter specifies whether to perform an exclusive
-        or non-exclusive backup (default is exclusive).
-       </para>
-       <para>
-        When used in exclusive mode, this function writes a backup label file
-        (<filename>backup_label</filename>) and, if there are any links in
-        the <filename>pg_tblspc/</filename> directory, a tablespace map file
-        (<filename>tablespace_map</filename>) into the database cluster's data
-        directory, then performs a checkpoint, and then returns the backup's
-        starting write-ahead log location.  (The user can ignore this
-        result value, but it is provided in case it is useful.)  When used in
-        non-exclusive mode, the contents of these files are instead returned
-        by the <function>pg_stop_backup</function> function, and should be
-        copied to the backup area by the user.
        </para>
        <para>
         This function is restricted to superusers by default, but other users
@@ -25751,36 +25735,32 @@ LOG:  Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
-         <primary>pg_stop_backup</primary>
+         <primary>pg_backup_stop</primary>
         </indexterm>
-        <function>pg_stop_backup</function> (
-          <parameter>exclusive</parameter> <type>boolean</type>
-          <optional>, <parameter>wait_for_archive</parameter> <type>boolean</type>
+        <function>pg_backup_stop</function> (
+          <optional><parameter>wait_for_archive</parameter> <type>boolean</type>
           </optional> )
         <returnvalue>record</returnvalue>
         ( <parameter>lsn</parameter> <type>pg_lsn</type>,
         <parameter>labelfile</parameter> <type>text</type>,
         <parameter>spcmapfile</parameter> <type>text</type> )
        </para>
        <para>
-        Finishes performing an exclusive or non-exclusive on-line backup.
-        The <parameter>exclusive</parameter> parameter must match the
-        previous <function>pg_start_backup</function> call.
-        In an exclusive backup, <function>pg_stop_backup</function> removes
-        the backup label file and, if it exists, the tablespace map file
-        created by <function>pg_start_backup</function>.  In a non-exclusive
-        backup, the desired contents of these files are returned as part of
-        the result of the function, and should be written to files in the
-        backup area (not in the data directory).
+        Finishes performing an on-line backup.  The desired contents of the
+        backup label file and the tablespace map file are returned as part of
+        the result of the function and must be written to files in the
+        backup area.  These files must not be written to the live data directory
+        (doing so will cause PostgreSQL to fail to restart in the event of a
+        crash).
        </para>
        <para>
-        There is an optional second parameter of type <type>boolean</type>.
+        There is an optional parameter of type <type>boolean</type>.
         If false, the function will return immediately after the backup is
         completed, without waiting for WAL to be archived.  This behavior is
         only useful with backup software that independently monitors WAL
         archiving.  Otherwise, WAL required to make the backup consistent might
         be missing and make the backup useless.  By default or when this
-        parameter is true, <function>pg_stop_backup</function> will wait for
+        parameter is true, <function>pg_backup_stop</function> will wait for
         WAL to be archived when archiving is enabled.  (On a standby, this
         means that it will wait only when <varname>archive_mode</varname> =
         <literal>always</literal>.  If write activity on the primary is low,
@@ -25790,7 +25770,7 @@ LOG:  Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
        <para>
         When executed on a primary, this function also creates a backup
         history file in the write-ahead log archive area.  The history file
-        includes the label given to <function>pg_start_backup</function>, the
+        includes the label given to <function>pg_backup_start</function>, the
         starting and ending write-ahead log locations for the backup, and the
         starting and ending times of the backup.  After recording the ending
         location, the current write-ahead log insertion point is automatically
@@ -25801,61 +25781,18 @@ LOG:  Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
        <para>
         The result of the function is a single record.
         The <parameter>lsn</parameter> column holds the backup's ending
-        write-ahead log location (which again can be ignored).  The second and
-        third columns are <literal>NULL</literal> when ending an exclusive
-        backup; after a non-exclusive backup they hold the desired contents of
-        the label and tablespace map files.
-       </para>
-       <para>
-        This function is restricted to superusers by default, but other users
-        can be granted EXECUTE to run the function.
-       </para></entry>
-      </row>
-
-      <row>
-       <entry role="func_table_entry"><para role="func_signature">
-        <function>pg_stop_backup</function> ()
-        <returnvalue>pg_lsn</returnvalue>
-       </para>
-       <para>
-        Finishes performing an exclusive on-line backup.  This simplified
-        version is equivalent to <literal>pg_stop_backup(true,
-        true)</literal>, except that it only returns the <type>pg_lsn</type>
-        result.
+        write-ahead log location (which again can be ignored).  The second
+        column returns the contents of the backup label file, and the third
+        column returns the contents of the tablespace map file.  These must be
+        stored as part of the backup and are required as part of the restore
+        process.
        </para>
        <para>
         This function is restricted to superusers by default, but other users
         can be granted EXECUTE to run the function.
        </para></entry>
       </row>
 
-      <row>
-       <entry role="func_table_entry"><para role="func_signature">
-        <indexterm>
-         <primary>pg_is_in_backup</primary>
-        </indexterm>
-        <function>pg_is_in_backup</function> ()
-        <returnvalue>boolean</returnvalue>
-       </para>
-       <para>
-        Returns true if an on-line exclusive backup is in progress.
-       </para></entry>
-      </row>
-
-      <row>
-       <entry role="func_table_entry"><para role="func_signature">
-        <indexterm>
-         <primary>pg_backup_start_time</primary>
-        </indexterm>
-        <function>pg_backup_start_time</function> ()
-        <returnvalue>timestamp with time zone</returnvalue>
-       </para>
-       <para>
-        Returns the start time of the current on-line exclusive backup if one
-        is in progress, otherwise <literal>NULL</literal>.
-       </para></entry>
-      </row>
-
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
@@ -25953,7 +25890,7 @@ LOG:  Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
     corresponding write-ahead log file name and byte offset from
     a <type>pg_lsn</type> value.  For example:
 <programlisting>
-postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
+postgres=# SELECT * FROM pg_walfile_name_offset((pg_backup_stop()).lsn);
         file_name         | file_offset
 --------------------------+-------------
  00000001000000000000000D |     4039624

doc/src/sgml/func.sgml

@@ -1361,8 +1361,8 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
 
    <para>
     If you need to re-create a standby server while transactions are
-    waiting, make sure that the commands pg_start_backup() and
-    pg_stop_backup() are run in a session with
+    waiting, make sure that the commands pg_backup_start() and
+    pg_backup_stop() are run in a session with
     <varname>synchronous_commit</varname> = <literal>off</literal>, otherwise those
     requests will wait forever for the standby to appear.
    </para>
@@ -2159,7 +2159,7 @@ HINT:  You can then restart the server after making the necessary configuration
 
    <para>
     WAL file control commands will not work during recovery,
-    e.g., <function>pg_start_backup</function>, <function>pg_switch_wal</function> etc.
+    e.g., <function>pg_backup_start</function>, <function>pg_switch_wal</function> etc.
    </para>
 
    <para>

doc/src/sgml/high-availability.sgml

@@ -6674,7 +6674,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
       <entry><literal>waiting for checkpoint to finish</literal></entry>
       <entry>
        The WAL sender process is currently performing
-       <function>pg_start_backup</function> to prepare to
+       <function>pg_backup_start</function> to prepare to
        take a base backup, and waiting for the start-of-backup
        checkpoint to finish.
       </entry>
@@ -6697,7 +6697,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
       <entry><literal>waiting for wal archiving to finish</literal></entry>
       <entry>
        The WAL sender process is currently performing
-       <function>pg_stop_backup</function> to finish the backup,
+       <function>pg_backup_stop</function> to finish the backup,
        and waiting for all the WAL files required for the base backup
        to be successfully archived.
        If either <literal>--wal-method=none</literal> or

doc/src/sgml/monitoring.sgml

@@ -186,11 +186,11 @@ PostgreSQL documentation
    the specified data directory.  Three different
    shutdown methods can be selected with the <option>-m</option>
    option.  <quote>Smart</quote> mode disallows new connections, then waits
-   for all existing clients to disconnect and any online backup to finish.
+   for all existing clients to disconnect.
    If the server is in hot standby, recovery and streaming replication
    will be terminated once all clients have disconnected.
-   <quote>Fast</quote> mode (the default) does not wait for clients to disconnect and
-   will terminate an online backup in progress.  All active transactions are
+   <quote>Fast</quote> mode (the default) does not wait for clients to disconnect.
+   All active transactions are
    rolled back and clients are forcibly disconnected, then the
    server is shut down.  <quote>Immediate</quote> mode will abort
    all server processes immediately, without a clean shutdown.  This choice

doc/src/sgml/ref/pg_ctl-ref.sgml

@@ -618,7 +618,7 @@ rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tb
 
       <para>
        Configure the servers for log shipping.  (You do not need to run
-       <function>pg_start_backup()</function> and <function>pg_stop_backup()</function>
+       <function>pg_backup_start()</function> and <function>pg_backup_stop()</function>
        or take a file system backup as the standbys are still synchronized
        with the primary.)
       </para>

doc/src/sgml/ref/pgupgrade.sgml

@@ -1552,11 +1552,7 @@ $ <userinput>cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages</userinp
        After receiving <systemitem>SIGTERM</systemitem>, the server
        disallows new connections, but lets existing sessions end their
        work normally. It shuts down only after all of the sessions terminate.
-       If the server is in online backup mode, it additionally waits
-       until online backup mode is no longer active.  While backup mode is
-       active, new connections will still be allowed, but only to superusers
-       (this exception allows a superuser to connect to terminate
-       online backup mode).  If the server is in recovery when a smart
+       If the server is in recovery when a smart
        shutdown is requested, recovery and streaming replication will be
        stopped only after all regular sessions have terminated.
       </para>
@@ -1572,8 +1568,6 @@ $ <userinput>cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages</userinp
        server processes <systemitem>SIGTERM</systemitem>, which will cause them
        to abort their current transactions and exit promptly. It then
        waits for all server processes to exit and finally shuts down.
-       If the server is in online backup mode, backup mode will be
-       terminated, rendering the backup useless.
       </para>
      </listitem>
     </varlistentry>