From 68beedac7e529a81ebf58ff40d30b28e404b30f5 Mon Sep 17 00:00:00 2001
From: David Steele <david@pgmasters.net>
Date: Thu, 28 Feb 2019 16:55:42 +0200
Subject: [PATCH] Add exclusive backup deprecation notes to documentation.

Update the exclusive backup documentation to explain the limitations of the exclusive backup mode and make it clear that the feature is deprecated.
---
 doc/src/sgml/backup.sgml | 42 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index a73fd4d044..de1a8a5826 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -948,6 +948,48 @@ SELECT * FROM pg_stop_backup(false, true);
    </sect3>
    <sect3 id="backup-lowlevel-base-backup-exclusive">
     <title>Making an exclusive low level backup</title>
+
+  <note>
+   <para>
+     The exclusive backup method is deprecated and should be avoided in favor
+     of the non-exclusive backup method or
+     <application>pg_basebackup</application>.
+   </para>
+
+   <para>
+     The primary issue with the exclusive method is that the
+     <filename>backup_label</filename> file is written into the data directory
+     when <function>pg_start_backup</function> is called and remains until
+     <function>pg_stop_backup</function> is called.  If
+     <productname>PostgreSQL</productname> or the host terminates abnormally
+     then <filename>backup_label</filename> will be left in the data directory
+     and <productname>PostgreSQL</productname> will not start. A log message
+     recommends that <filename>backup_label</filename> be removed if not
+     restoring from a backup.
+   </para>
+
+   <para>
+     However, if <filename>backup_label</filename> is present because a restore
+     is actually in progress, then removing it will result in corruption.  For
+     this reason it is not recommended to automate the removal of
+     <filename>backup_label</filename>.
+   </para>
+
+   <para>
+     Another issue with exclusive backup mode is that it will continue until
+     <function>pg_stop_backup</function> is called, even if the calling process
+     is no longer performing the backup.  The next time
+     <function>pg_start_backup</function> is called it will fail unless
+     <function>pg_stop_backup</function> is called manually first.
+   </para>
+
+   <para>
+     Finally, only one exclusive backup may be run at a time.  However, it is
+     possible to run an exclusive backup at the same time as any number of
+     non-exclusive backups.
+   </para>
+  </note>
+
     <para>
      The process for an exclusive backup is mostly the same as for a
      non-exclusive one, but it differs in a few key steps. This type of backup
-- 
2.17.2 (Apple Git-113)