Retire pg_standby.

pg_standby was useful more than a decade ago, but now it is obsolete.
It has been proposed that we retire it many times.  Now seems like a
good time to finally do it, because "waiting restore commands"
are incompatible with a proposed recovery prefetching feature.

Discussion: https://postgr.es/m/20201029024412.GP5380%40telsasoft.com
Author: Justin Pryzby <pryzby@telsasoft.com>
Reviewed-by: Heikki Linnakangas <hlinnaka@iki.fi>
Reviewed-by: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
Reviewed-by: Michael Paquier <michael@paquier.xyz>
Reviewed-by: Fujii Masao <masao.fujii@oss.nttdata.com>

5 files changed, 6 insertions, 420 deletions

diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index ae2759be553..d3ca4b69320 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -192,13 +192,12 @@ pages.
   <title>Server Applications</title>
 
   <para>
-   This section covers <productname>PostgreSQL</productname> server-related
-   applications in <literal>contrib</literal>.  They are typically run on the
-   host where the database server resides.  See also <xref
+   Some applications run on the <productname>PostgreSQL</productname> server
+   itself.  Currently, no such applications are included in the
+   <literal>contrib</literal> directory.  See also <xref
    linkend="reference-server"/> for information about server applications that
    are part of the core <productname>PostgreSQL</productname> distribution.
   </para>
 
- &pgstandby;
  </sect1>
 </appendix>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 38e8aa0bbf9..db1d369743e 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -138,7 +138,6 @@
 <!ENTITY pgfreespacemap  SYSTEM "pgfreespacemap.sgml">
 <!ENTITY pgprewarm       SYSTEM "pgprewarm.sgml">
 <!ENTITY pgrowlocks      SYSTEM "pgrowlocks.sgml">
-<!ENTITY pgstandby       SYSTEM "pgstandby.sgml">
 <!ENTITY pgstatstatements SYSTEM "pgstatstatements.sgml">
 <!ENTITY pgstattuple     SYSTEM "pgstattuple.sgml">
 <!ENTITY pgsurgery       SYSTEM "pgsurgery.sgml">
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index dc263e41067..9364dc74f71 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -699,11 +699,9 @@ protocol to make nodes agree on a serializable transactional order.
 
    <note>
      <para>
-     Do not use pg_standby or similar tools with the built-in standby mode
-     described here. <xref linkend="guc-restore-command"/> should return immediately
+     <xref linkend="guc-restore-command"/> should return immediately
      if the file does not exist; the server will retry the command again if
-     necessary. See <xref linkend="log-shipping-alternative"/>
-     for using tools like pg_standby.
+     necessary.
     </para>
    </note>
 
@@ -1494,8 +1492,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
    <para>
     An alternative to the built-in standby mode described in the previous
     sections is to use a <varname>restore_command</varname> that polls the archive location.
-    This was the only option available in versions 8.4 and below. See the
-    <xref linkend="pgstandby"/> module for a reference implementation of this.
+    This was the only option available in versions 8.4 and below.
    </para>
 
    <para>
@@ -1552,14 +1549,6 @@ if (!triggered)
    </para>
 
    <para>
-    A working example of a waiting <varname>restore_command</varname> is provided
-    in the <xref linkend="pgstandby"/> module. It
-    should be used as a reference on how to correctly implement the logic
-    described above. It can also be extended as needed to support specific
-    configurations and environments.
-   </para>
-
-   <para>
     The method for triggering failover is an important part of planning
     and design. One potential option is the <varname>restore_command</varname>
     command.  It is executed once for each WAL file, but the process
diff --git a/doc/src/sgml/pgstandby.sgml b/doc/src/sgml/pgstandby.sgml
deleted file mode 100644
index 66a62559303..00000000000
--- a/doc/src/sgml/pgstandby.sgml
+++ /dev/null
@@ -1,394 +0,0 @@
-<!-- doc/src/sgml/pgstandby.sgml -->
-
-<refentry id="pgstandby">
- <indexterm zone="pgstandby">
-  <primary>pg_standby</primary>
- </indexterm>
-
- <refmeta>
-  <refentrytitle><application>pg_standby</application></refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo>Application</refmiscinfo>
- </refmeta>
-
- <refnamediv>
-  <refname>pg_standby</refname>
-  <refpurpose>supports the creation of a <productname>PostgreSQL</productname> warm standby server</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
-  <cmdsynopsis>
-   <command>pg_standby</command>
-   <arg rep="repeat"><replaceable>option</replaceable></arg>
-   <arg choice="plain"><replaceable>archivelocation</replaceable></arg>
-   <arg choice="plain"><replaceable>nextwalfile</replaceable></arg>
-   <arg choice="plain"><replaceable>walfilepath</replaceable></arg>
-   <arg choice="opt"><replaceable>restartwalfile</replaceable></arg>
-  </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
-  <title>Description</title>
-
- <para>
-  <application>pg_standby</application> supports creation of a <quote>warm standby</quote>
-  database server.  It is designed to be a production-ready program, as well
-  as a customizable template should you require specific modifications.
- </para>
-
- <para>
-  <application>pg_standby</application> is designed to be a waiting
-  <varname>restore_command</varname>, which is needed to turn a standard
-  archive recovery into a warm standby operation.  Other
-  configuration is required as well, all of which is described in the main
-  server manual (see <xref linkend="warm-standby"/>).
- </para>
-
-  <para>
-   To configure a standby
-   server to use <application>pg_standby</application>, put this into its
-   <filename>postgresql.conf</filename> configuration file:
-<programlisting>
-restore_command = 'pg_standby <replaceable>archiveDir</replaceable> %f %p %r'
-</programlisting>
-   where <replaceable>archiveDir</replaceable> is the directory from which WAL segment
-   files should be restored.
-  </para>
-  <para>
-   If <replaceable>restartwalfile</replaceable> is specified, normally by using the
-   <literal>%r</literal> macro, then all WAL files logically preceding this
-   file will be removed from <replaceable>archivelocation</replaceable>. This minimizes
-   the number of files that need to be retained, while preserving
-   crash-restart capability.  Use of this parameter is appropriate if the
-   <replaceable>archivelocation</replaceable> is a transient staging area for this
-   particular standby server, but <emphasis>not</emphasis> when the
-   <replaceable>archivelocation</replaceable> is intended as a long-term WAL archive area.
-  </para>
-  <para>
-   <application>pg_standby</application> assumes that
-   <replaceable>archivelocation</replaceable> is a directory readable by the
-   server-owning user.  If <replaceable>restartwalfile</replaceable> (or <literal>-k</literal>)
-   is specified,
-   the <replaceable>archivelocation</replaceable> directory must be writable too.
-  </para>
-  <para>
-   There are two ways to fail over to a <quote>warm standby</quote> database server
-   when the primary server fails:
-
-   <variablelist>
-    <varlistentry>
-     <term>Smart Failover</term>
-     <listitem>
-      <para>
-       In smart failover, the server is brought up after applying all WAL
-       files available in the archive. This results in zero data loss, even if
-       the standby server has fallen behind, but if there is a lot of
-       unapplied WAL it can be a long time before the standby server becomes
-       ready. To trigger a smart failover, create a trigger file containing
-       the word <literal>smart</literal>, or just create it and leave it empty.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term>Fast Failover</term>
-     <listitem>
-      <para>
-       In fast failover, the server is brought up immediately. Any WAL files
-       in the archive that have not yet been applied will be ignored, and
-       all transactions in those files are lost. To trigger a fast failover,
-       create a trigger file and write the word <literal>fast</literal> into it.
-       <application>pg_standby</application> can also be configured to execute a fast
-       failover automatically if no new WAL file appears within a defined
-       interval.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
-
- </refsect1>
-
- <refsect1>
-  <title>Options</title>
-
-   <para>
-    <application>pg_standby</application> accepts the following command-line arguments:
-
-    <variablelist>
-
-     <varlistentry>
-      <term><option>-c</option></term>
-      <listitem>
-       <para>
-        Use <literal>cp</literal> or <literal>copy</literal> command to restore WAL files
-        from archive.  This is the only supported behavior so this option is useless.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>-d</option></term>
-      <listitem>
-       <para>
-        Print lots of debug logging output on <filename>stderr</filename>.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>-k</option></term>
-      <listitem>
-       <para>
-        Remove files from <replaceable>archivelocation</replaceable> so that
-        no more than this many WAL files before the current one are kept in the
-        archive.  Zero (the default) means not to remove any files from
-        <replaceable>archivelocation</replaceable>.
-        This parameter will be silently ignored if
-        <replaceable>restartwalfile</replaceable> is specified, since that
-        specification method is more accurate in determining the correct
-        archive cut-off point.
-        Use of this parameter is <emphasis>deprecated</emphasis> as of
-        <productname>PostgreSQL</productname> 8.3; it is safer and more efficient to
-        specify a <replaceable>restartwalfile</replaceable> parameter.  A too
-        small setting could result in removal of files that are still needed
-        for a restart of the standby server, while a too large setting wastes
-        archive space.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>-r</option> <replaceable>maxretries</replaceable></term>
-      <listitem>
-       <para>
-        Set the maximum number of times to retry the copy command if
-        it fails (default 3). After each failure, we wait for
-        <replaceable>sleeptime</replaceable> * <replaceable>num_retries</replaceable>
-        so that the wait time increases progressively.  So by default,
-        we will wait 5 secs, 10 secs, then 15 secs before reporting
-        the failure back to the standby server. This will be
-        interpreted as end of recovery and the standby will come
-        up fully as a result.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>-s</option> <replaceable>sleeptime</replaceable></term>
-      <listitem>
-       <para>
-        Set the number of seconds (up to 60, default 5) to sleep between
-        tests to see if the WAL file to be restored is available in
-        the archive yet.  The default setting is not necessarily
-        recommended; consult <xref linkend="warm-standby"/> for discussion.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>-t</option> <replaceable>triggerfile</replaceable></term>
-      <listitem>
-       <para>
-        Specify a trigger file whose presence should cause failover.
-        It is recommended that you use a structured file name to
-        avoid confusion as to which server is being triggered
-        when multiple servers exist on the same system; for example
-        <filename>/tmp/pgsql.trigger.5432</filename>.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>-V</option></term>
-      <term><option>--version</option></term>
-      <listitem>
-       <para>
-        Print the <application>pg_standby</application> version and exit.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>-w</option> <replaceable>maxwaittime</replaceable></term>
-      <listitem>
-       <para>
-        Set the maximum number of seconds to wait for the next WAL file,
-        after which a fast failover will be performed.
-        A setting of zero (the default) means wait forever.
-        The default setting is not necessarily recommended;
-        consult <xref linkend="warm-standby"/> for discussion.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><option>-?</option></term>
-      <term><option>--help</option></term>
-      <listitem>
-       <para>
-        Show help about <application>pg_standby</application> command line
-        arguments, and exit.
-       </para>
-      </listitem>
-     </varlistentry>
-    </variablelist>
-   </para>
-
- </refsect1>
-
- <refsect1>
-  <title>Notes</title>
-
-  <para>
-   <application>pg_standby</application> is designed to work with
-   <productname>PostgreSQL</productname> 8.2 and later.
-  </para>
-  <para>
-   <productname>PostgreSQL</productname> 8.3 provides the <literal>%r</literal> macro,
-   which is designed to let <application>pg_standby</application> know the
-   last file it needs to keep.  With <productname>PostgreSQL</productname> 8.2, the
-   <literal>-k</literal> option must be used if archive cleanup is
-   required.  This option remains available in 8.3, but its use is deprecated.
-  </para>
-  <para>
-   <productname>PostgreSQL</productname> 8.4 provides the
-   <varname>recovery_end_command</varname> option.  Without this option
-   a leftover trigger file can be hazardous.
-  </para>
-
-  <para>
-   <application>pg_standby</application> is written in C and has an
-   easy-to-modify source code, with specifically designated sections to modify
-   for your own needs
-  </para>
- </refsect1>
-
- <refsect1>
-  <title>Examples</title>
-
-  <para>On Linux or Unix systems, you might use:
-
-<programlisting>
-archive_command = 'cp %p .../archive/%f'
-
-restore_command = 'pg_standby -d -s 2 -t /tmp/pgsql.trigger.5442 .../archive %f %p %r 2>>standby.log'
-
-recovery_end_command = 'rm -f /tmp/pgsql.trigger.5442'
-</programlisting>
-   where the archive directory is physically located on the standby server,
-   so that the <varname>archive_command</varname> is accessing it across NFS,
-   but the files are local to the standby (enabling use of <literal>ln</literal>).
-   This will:
-  <itemizedlist>
-   <listitem>
-    <para>
-     produce debugging output in <filename>standby.log</filename>
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     sleep for 2 seconds between checks for next WAL file availability
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     stop waiting only when a trigger file called
-     <filename>/tmp/pgsql.trigger.5442</filename> appears,
-     and perform failover according to its content
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     remove the trigger file when recovery ends
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     remove no-longer-needed files from the archive directory
-    </para>
-   </listitem>
-  </itemizedlist>
-  </para>
-
-  <para>On Windows, you might use:
-
-<programlisting>
-archive_command = 'copy %p ...\\archive\\%f'
-
-restore_command = 'pg_standby -d -s 5 -t C:\pgsql.trigger.5442 ...\archive %f %p %r 2>>standby.log'
-
-recovery_end_command = 'del C:\pgsql.trigger.5442'
-</programlisting>
-   Note that backslashes need to be doubled in the
-   <varname>archive_command</varname>, but <emphasis>not</emphasis> in the
-   <varname>restore_command</varname> or <varname>recovery_end_command</varname>.
-   This will:
-  <itemizedlist>
-   <listitem>
-    <para>
-     use the <literal>copy</literal> command to restore WAL files from archive
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     produce debugging output in <filename>standby.log</filename>
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     sleep for 5 seconds between checks for next WAL file availability
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     stop waiting only when a trigger file called
-     <filename>C:\pgsql.trigger.5442</filename> appears,
-     and perform failover according to its content
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     remove the trigger file when recovery ends
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     remove no-longer-needed files from the archive directory
-    </para>
-   </listitem>
-  </itemizedlist>
-  </para>
-
-  <para>
-   The <literal>copy</literal> command on Windows sets the final file size
-   before the file is completely copied, which would ordinarily confuse
-   <application>pg_standby</application>.  Therefore
-   <application>pg_standby</application> waits <replaceable>sleeptime</replaceable>
-   seconds once it sees the proper file size.  GNUWin32's <literal>cp</literal>
-   sets the file size only after the file copy is complete.
-  </para>
-
-  <para>
-   Since the Windows example uses <literal>copy</literal> at both ends, either
-   or both servers might be accessing the archive directory across the
-   network.
-  </para>
-
- </refsect1>
-
- <refsect1>
-  <title>Author</title>
-
-  <para>
-   Simon Riggs <email>simon@2ndquadrant.com</email>
-  </para>
- </refsect1>
-
- <refsect1>
-  <title>See Also</title>
-
-  <simplelist type="inline">
-   <member><xref linkend="pgarchivecleanup"/></member>
-  </simplelist>
- </refsect1>
-</refentry>
diff --git a/doc/src/sgml/ref/pgarchivecleanup.sgml b/doc/src/sgml/ref/pgarchivecleanup.sgml
index 56f02fc0e62..e27db3c0773 100644
--- a/doc/src/sgml/ref/pgarchivecleanup.sgml
+++ b/doc/src/sgml/ref/pgarchivecleanup.sgml
@@ -205,11 +205,4 @@ archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>clean
   </itemizedlist>
  </refsect1>
 
- <refsect1>
-  <title>See Also</title>
-
-  <simplelist type="inline">
-   <member><xref linkend="pgstandby"/></member>
-  </simplelist>
- </refsect1>
 </refentry>