Warm standby patch - Mailing list pgsql-patches

I'm submitting this patch in attempt to clarify some issues with the
warm standby documentation which caused some confusion in our
organization and which have been recently discussed on the admin list.

-Kevin


Index: backup.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/backup.sgml,v
retrieving revision 2.98
diff -c -r2.98 backup.sgml
*** backup.sgml    29 Jun 2007 15:46:21 -0000    2.98
--- backup.sgml    29 Jun 2007 21:37:21 -0000
***************
*** 1402,1411 ****
      server. Normal recovery processing would request a file from the
      WAL archive, reporting failure if the file was unavailable.  For
      standby processing it is normal for the next file to be
!     unavailable, so we must be patient and wait for it to appear. A
!     waiting <varname>restore_command</> can be written as a custom
      script that loops after polling for the existence of the next WAL
!     file. There must also be some way to trigger failover, which
      should interrupt the <varname>restore_command</>, break the loop
      and return a file-not-found error to the standby server. This
      ends recovery and the standby will then come up as a normal
--- 1402,1423 ----
      server. Normal recovery processing would request a file from the
      WAL archive, reporting failure if the file was unavailable.  For
      standby processing it is normal for the next file to be
!     unavailable, so we must be patient and wait for it to appear.
!    </para>
!
!    <para>
!     A waiting <varname>restore_command</> can be written as a custom
      script that loops after polling for the existence of the next WAL
!     file. The script will occassionally be invoked with a request for
!     a file other than a WAL file.  Such a request can be identified
!     by a file name which is anything except 24 hexadecimal characters.
!     If the requested file is available, it should be copied; otherwise
!     the script should return a file-not-found error.  This does not
!     always terminate recovery mode.
!    </para>
!
!    <para>
!     There must also be some way to trigger failover, which
      should interrupt the <varname>restore_command</>, break the loop
      and return a file-not-found error to the standby server. This
      ends recovery and the standby will then come up as a normal
***************
*** 1415,1430 ****
     <para>
      Pseudocode for a suitable <varname>restore_command</> is:
  <programlisting>
! triggered = false;
! while (!NextWALFileReady() && !triggered)
  {
!     sleep(100000L);         /* wait for ~0.1 sec */
!     if (CheckForExternalTrigger())
!         triggered = true;
  }
! if (!triggered)
!         CopyWALFileForRecovery();
  </programlisting>
     </para>

     <para>
--- 1427,1446 ----
     <para>
      Pseudocode for a suitable <varname>restore_command</> is:
  <programlisting>
! if (RequestedFileIsNotWALFile())
!     return CopyFileForRecovery();
! while (!NextWALFileReady() && !CheckForExternalTrigger())
  {
!     sleep(pollingInterval);
  }
! return CopyFileForRecovery();
  </programlisting>
+     where CopyFileForRecovery() will return a file-not-found error when
+     the file doesn't exist, and zero for success when the copy succeeds.
+     If a large number is returned, the recovery process will interpret
+     this as indicating catastrophic failure, and will terminate the
+     standby instance of <productname>PostgreSQL</productname>, rather
+     than switching to a "ready" state.
     </para>

     <para>