On 2/28/19 6:08 PM, Laurenz Albe wrote:
David Steele wrote:
This patch attempts to document the limitations of the exclusive mode.
Thanks!
+ <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
There should be a comma at the end of this line.
Fixed.
+ then <filename>backup_label</filename> will be left in the data directory
+ and <productname>PostgreSQL</productname> will not start. A log message
You should say "*may* not start", because it will if the WAL segment is still
there.
You are correct. It's still pretty likely though so I went with "probably".
I added some extra language to the warning that gets emitted in the log.
Users are more like to see that than the documentation.
I also addressed a comment from another thread by adding pg_basebackup
as .e.g. rather than or.
Thanks,
--
-David
da...@pgmasters.net
From fa2391c9f843358d4e2264b62297eb10bbffcc5a Mon Sep 17 00:00:00 2001
From: David Steele <da...@pgmasters.net>
Date: Fri, 1 Mar 2019 11:14:41 +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.
Update the log message when the backup_label is found but recovery
cannot proceed.
---
doc/src/sgml/backup.sgml | 42 +++++++++++++++++++++++++++++++
src/backend/access/transam/xlog.c | 10 ++++++--
2 files changed, 50 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index a73fd4d044..1d09808b0d 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, e.g.
+ <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> probably 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
diff --git a/src/backend/access/transam/xlog.c
b/src/backend/access/transam/xlog.c
index ecd12fc53a..e12a04414b 100644
--- a/src/backend/access/transam/xlog.c
+++ b/src/backend/access/transam/xlog.c
@@ -6405,14 +6405,20 @@ StartupXLOG(void)
if (!ReadRecord(xlogreader, checkPoint.redo,
LOG, false))
ereport(FATAL,
(errmsg("could not find
redo location referenced by checkpoint record"),
- errhint("If you are
not restoring from a backup, try removing the file \"%s/backup_label\".",
DataDir)));
+ errhint("If you are
restoring from a backup, touch \"%s/recovery.signal\" and add recovery options
to \"%s/postgresql.auto.conf\".\n"
+ "If you are not
restoring from a backup, try removing the file \"%s/backup_label\".\n"
+ "Be careful: removing
\"%s/backup_label\" will result in a corrupt cluster if restoring from a
backup.",
+ DataDir, DataDir,
DataDir, DataDir)));
}
}
else
{
ereport(FATAL,
(errmsg("could not locate required
checkpoint record"),
- errhint("If you are not restoring from
a backup, try removing the file \"%s/backup_label\".", DataDir)));
+ errhint("If you are restoring from a
backup, touch \"%s/recovery.signal\" and add recovery options to
\"%s/postgresql.auto.conf\".\n"
+ "If you are not
restoring from a backup, try removing the file \"%s/backup_label\".\n"
+ "Be careful: removing
\"%s/backup_label\" will result in a corrupt cluster if restoring from a
backup.",
+ DataDir, DataDir,
DataDir, DataDir)));
wasShutdown = false; /* keep compiler quiet */
}
--
2.17.2 (Apple Git-113)
