Subject: docu bug?

From: PG Doc comments form <[email-masked]>
Date: Mon, 19 Feb 2018 13:54:24 +0000

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.6/static/continuous-archiving.html
Description:

Seems to need a persistent connection:

<quote>
25.3.3.1. Making a non-exclusive low level backup
...
The connection calling pg_start_backup must be maintained until the end of
the backup, or the backup will be automatically aborted.
...
</Quote>

The sample works with a NON-persistent connection (psql -c):

<quote>
25.3.6.1. Standalone Hot Backups
...      touch /var/lib/pgsql/backup_in_progress
psql -c "select pg_start_backup('hot_backup');"
tar -cf /var/lib/pgsql/backup.tar /var/lib/pgsql/data/
psql -c "select pg_stop_backup();"
rm /var/lib/pgsql/backup_in_progress
tar -rf /var/lib/pgsql/backup.tar /var/lib/pgsql/archive/
...
</quote>

---

From: Salvador Jacinto <[email-masked]>
Date: Mon, 19 Feb 2018 11:56:04 -0200

POR FAVOR TRADUZIR

---

From: Michael Paquier <[email-masked]>
Date: Tue, 20 Feb 2018 10:25:05 +0900

> tar -rf /var/lib/pgsql/backup.tar /var/lib/pgsql/archive/

This uses the set of exclusive backup APIs, so with non-persistent
connections the backup can be correctly completed.  Non-exclusive
backups can be defined using 'false' as third argument of 
pg_start_backup() and first argument of pg_stop_backup().  Note that for
pg_start_backup you would also need to define the second boolean
argument to decide if a checkpoint should be immediately taken or not.
So you would have basically the following flow on a persistem
connection:
=# SELECT pg_start_backup('my_backup', true_or_false, false);
-- keep connection alive and do stuff.
=# SELECT pg_stop_backup(false);

Do you think that the section "Tips and Examples" should mention
that an exclusive backup method is used for this example?  This may
reduce the confusion.
--
Michael

---

From: "Zwettler Markus (OIZ)" <[email-masked]>
Date: Tue, 20 Feb 2018 08:00:35 +0000

Yes. I think the exclusive backup method should be mentioned especially as it is the older one.

- Markus

-----Ursprüngliche Nachricht-----
Von: Michael Paquier [mailto:[email-masked]] 
Gesendet: Dienstag, 20. Februar 2018 02:25
An: Zwettler Markus (OIZ) <[email-masked]>; [email-masked]
Betreff: Re: docu bug?

On Mon, Feb 19, 2018 at 01:54:24PM +0000, PG Doc comments form wrote:
> tar -cf /var/lib/pgsql/backup.tar /var/lib/pgsql/data/ psql -c "select 
> pg_stop_backup();"
> tar -rf /var/lib/pgsql/backup.tar /var/lib/pgsql/archive/ ...
> </quote>

This uses the set of exclusive backup APIs, so with non-persistent connections the backup can be correctly completed.  Non-exclusive backups can be defined using 'false' as third argument of
pg_start_backup() and first argument of pg_stop_backup().  Note that for pg_start_backup you would also need to define the second boolean argument to decide if a checkpoint should be immediately taken or not.
So you would have basically the following flow on a persistem
connection:
=# SELECT pg_start_backup('my_backup', true_or_false, false);
-- keep connection alive and do stuff.
=# SELECT pg_stop_backup(false);

Do you think that the section "Tips and Examples" should mention that an exclusive backup method is used for this example?  This may reduce the confusion.
--
Michael

---

From: Michael Paquier <[email-masked]>
Date: Tue, 20 Feb 2018 18:55:32 +0900

> especially as it is the older one. 

Attached is a suggestion of patch.  What do you think?
--
Michael
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 9d8e69056f..54ead81e51 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1466,7 +1466,7 @@ archive_command = 'test ! -f /var/lib/pgsql/backup_in_progress || (test ! -f /va
 
      <para>
       With this preparation, a backup can be taken using a script like the
-      following:
+      following, which uses the exclusive backup method:
 <programlisting>
 touch /var/lib/pgsql/backup_in_progress
 psql -c "select pg_start_backup('hot_backup');"