Hackers,
It has been noted on multiple threads, such as [1], that it would be
good to have additional notes in the documentation to explain why
exclusive backups have been deprecated and why they should be avoided
when possible.
This patch attempts to document the limitations of the exclusive mode.
--
-David
da...@pgmasters.net
[1]
https://www.postgresql.org/message-id/flat/ac7339ca-3718-3c93-929f-99e725d1172c%40pgmasters.net
From 68beedac7e529a81ebf58ff40d30b28e404b30f5 Mon Sep 17 00:00:00 2001
From: David Steele <da...@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)
