pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedPossible mistake in backup documentation
5+ messages / 4 participants
[nested] [flat]
* Possible mistake in backup documentation
@ 2020-09-22 14:17 PG Doc comments form <noreply@postgresql.org>
2020-09-25 12:32 ` Re: Possible mistake in backup documentation Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 5+ messages in thread
From: PG Doc comments form @ 2020-09-22 14:17 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: abo@velvica.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/wal.html
Description:
Hello!
In "25.3.3.2. Making An Exclusive Low-Level Backup", you said that "The
exclusive backup method is deprecated and should be avoided. Prior to
PostgreSQL 9.6, this was the only low-level method available, but it is now
recommended that all users upgrade their scripts to use non-exclusive
backups". But in the example in "25.3.6.1. Standalone Hot Backups" you use
the exclusive version of backup command. Is it a mistake or not?
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Possible mistake in backup documentation
2020-09-22 14:17 Possible mistake in backup documentation PG Doc comments form <noreply@postgresql.org>
@ 2020-09-25 12:32 ` Laurenz Albe <laurenz.albe@cybertec.at>
2020-09-25 12:50 ` Re: Possible mistake in backup documentation Magnus Hagander <magnus@hagander.net>
0 siblings, 1 reply; 5+ messages in thread
From: Laurenz Albe @ 2020-09-25 12:32 UTC (permalink / raw)
To: abo@velvica.com; pgsql-docs@lists.postgresql.org
On Tue, 2020-09-22 at 14:17 +0000, PG Doc comments form wrote:
> In "25.3.3.2. Making An Exclusive Low-Level Backup", you said that "The
> exclusive backup method is deprecated and should be avoided. Prior to
> PostgreSQL 9.6, this was the only low-level method available, but it is now
> recommended that all users upgrade their scripts to use non-exclusive
> backups". But in the example in "25.3.6.1. Standalone Hot Backups" you use
> the exclusive version of backup command. Is it a mistake or not?
Yes, that's true.
How about the attached patch?
Perhaps that is too complicated, but I have no idea how to make it simpler.
Ceterum censeo, we should not deprecate the exclusive backup API.
Yours,
Laurenz Albe
Attachments:
0001-Use-non-exclusive-backup-in-example.patch (text/x-patch, 2.1K) download
From 283fa644c15b08894fdff957e57e526b85913951 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Fri, 25 Sep 2020 14:26:58 +0200
Subject: [PATCH] Use non-exclusive backup in example
Since we habe deprecated the exclusive backup API, we should not
use it in examples.
Discussion: https://postgr.es/m/160078426053.14061.808669930112439771@wrigleys.postgresql.org
---
doc/src/sgml/backup.sgml | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index b9331830f7..ddf2aa3f35 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1496,15 +1496,19 @@ archive_command = 'test ! -f /var/lib/pgsql/backup_in_progress || (test ! -f /va
following:
<programlisting>
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/
+mkdir /tmp/data
+psql -Atq -c "select pg_start_backup(label => 'hot_backup', exclusive => FALSE);" \
+ -c "\! tar -cf /var/lib/pgsql/backup.tar -C /var/lib/pgsql/ data/" \
+ -c "\o /tmp/data/backup_label" \
+ -c "SELECT labelfile FROM pg_stop_backup(exclusive => FALSE);"
+tar -rf /var/lib/pgsql/backup.tar -C /tmp data/backup_label
+rm -r /var/lib/pgsql/backup_in_progress /tmp/data
+tar -rf /var/lib/pgsql/backup.tar -C /var/lib/pgsql/ archive/
</programlisting>
The switch file <filename>/var/lib/pgsql/backup_in_progress</filename> is
created first, enabling archiving of completed WAL files to occur.
- After the backup the switch file is removed. Archived WAL files are
+ After the backup the switch file is removed. <filename>backup_label</filename>
+ and archived WAL files are
then added to the backup so that both base backup and all required
WAL files are part of the same <application>tar</application> file.
Please remember to add error handling to your backup scripts.
--
2.26.2
* Re: Possible mistake in backup documentation
2020-09-22 14:17 Possible mistake in backup documentation PG Doc comments form <noreply@postgresql.org>
2020-09-25 12:32 ` Re: Possible mistake in backup documentation Laurenz Albe <laurenz.albe@cybertec.at>
@ 2020-09-25 12:50 ` Magnus Hagander <magnus@hagander.net>
2020-09-28 08:50 ` Re: Possible mistake in backup documentation Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 5+ messages in thread
From: Magnus Hagander @ 2020-09-25 12:50 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: abo@velvica.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On Fri, Sep 25, 2020 at 2:32 PM Laurenz Albe <laurenz.albe@cybertec.at>
wrote:
> On Tue, 2020-09-22 at 14:17 +0000, PG Doc comments form wrote:
> > In "25.3.3.2. Making An Exclusive Low-Level Backup", you said that "The
> > exclusive backup method is deprecated and should be avoided. Prior to
> > PostgreSQL 9.6, this was the only low-level method available, but it is
> now
> > recommended that all users upgrade their scripts to use non-exclusive
> > backups". But in the example in "25.3.6.1. Standalone Hot Backups" you
> use
> > the exclusive version of backup command. Is it a mistake or not?
>
> Yes, that's true.
>
Well, technically it is *correct*. It's just rather silly that we are using
the deprecated API in the example.
How about the attached patch?
>
> Perhaps that is too complicated, but I have no idea how to make it simpler.
>
For this example, can't we just show two sessions. That is, "in a psql, run
pg_start_backup(). Then in a different session, copy all the files, and
then back in psql run pg_stop_backup()" or such?
This is still just an example of a low level operation, where the
recommendation is (and is there iirc) to use a different tool for it
already.
> Ceterum censeo, we should not deprecate the exclusive backup API.
>
Well. We should depreciate the way it works now, but we should also provide
a *better* way to solve the actual problem. This is not necessarily an API
that looks the way the deprecated one looks -- the focus should be on
providing a solution to the problem, not to un-deprecate the API.
--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/;
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Possible mistake in backup documentation
2020-09-22 14:17 Possible mistake in backup documentation PG Doc comments form <noreply@postgresql.org>
2020-09-25 12:32 ` Re: Possible mistake in backup documentation Laurenz Albe <laurenz.albe@cybertec.at>
2020-09-25 12:50 ` Re: Possible mistake in backup documentation Magnus Hagander <magnus@hagander.net>
@ 2020-09-28 08:50 ` Laurenz Albe <laurenz.albe@cybertec.at>
2020-10-07 14:12 ` Re: Possible mistake in backup documentation Stephen Frost <sfrost@snowman.net>
0 siblings, 1 reply; 5+ messages in thread
From: Laurenz Albe @ 2020-09-28 08:50 UTC (permalink / raw)
To: Magnus Hagander <magnus@hagander.net>; +Cc: abo@velvica.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On Fri, 2020-09-25 at 14:50 +0200, Magnus Hagander wrote:
> On Fri, Sep 25, 2020 at 2:32 PM Laurenz Albe <laurenz.albe@cybertec.at> wrote:
> > On Tue, 2020-09-22 at 14:17 +0000, PG Doc comments form wrote:
> > > In "25.3.3.2. Making An Exclusive Low-Level Backup", you said that "The
> > > exclusive backup method is deprecated and should be avoided. Prior to
> > > PostgreSQL 9.6, this was the only low-level method available, but it is now
> > > recommended that all users upgrade their scripts to use non-exclusive
> > > backups". But in the example in "25.3.6.1. Standalone Hot Backups" you use
> > > the exclusive version of backup command. Is it a mistake or not?
> >
> > Yes, that's true.
>
> Well, technically it is *correct*. It's just rather silly that we are using the deprecated API in the example.
>
> > How about the attached patch?
> > Perhaps that is too complicated, but I have no idea how to make it simpler.
>
> For this example, can't we just show two sessions. That is, "in a psql, run pg_start_backup().
> Then in a different session, copy all the files, and then back in psql run pg_stop_backup()" or such?
>
> This is still just an example of a low level operation, where the recommendation is (and is there iirc)
> to use a different tool for it already.
I thought the point of the example is to show a workable script that could
perform a backup and could be used as a starting point to develop your own
backup solution. (I know that there are people who think writing your own
backup solution is evil, but I am not one of them.)
If we replace that with a verbal description of how to do it, the example just
duplicates what is already documented.
In that case I would opt for simply removing the example.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Possible mistake in backup documentation
2020-09-22 14:17 Possible mistake in backup documentation PG Doc comments form <noreply@postgresql.org>
2020-09-25 12:32 ` Re: Possible mistake in backup documentation Laurenz Albe <laurenz.albe@cybertec.at>
2020-09-25 12:50 ` Re: Possible mistake in backup documentation Magnus Hagander <magnus@hagander.net>
2020-09-28 08:50 ` Re: Possible mistake in backup documentation Laurenz Albe <laurenz.albe@cybertec.at>
@ 2020-10-07 14:12 ` Stephen Frost <sfrost@snowman.net>
0 siblings, 0 replies; 5+ messages in thread
From: Stephen Frost @ 2020-10-07 14:12 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Magnus Hagander <magnus@hagander.net>; abo@velvica.com, Pg Docs <pgsql-docs@lists.postgresql.org>
Greetings,
* Laurenz Albe (laurenz.albe@cybertec.at) wrote:
> On Fri, 2020-09-25 at 14:50 +0200, Magnus Hagander wrote:
> > On Fri, Sep 25, 2020 at 2:32 PM Laurenz Albe <laurenz.albe@cybertec.at> wrote:
> > > On Tue, 2020-09-22 at 14:17 +0000, PG Doc comments form wrote:
> > > > In "25.3.3.2. Making An Exclusive Low-Level Backup", you said that "The
> > > > exclusive backup method is deprecated and should be avoided. Prior to
> > > > PostgreSQL 9.6, this was the only low-level method available, but it is now
> > > > recommended that all users upgrade their scripts to use non-exclusive
> > > > backups". But in the example in "25.3.6.1. Standalone Hot Backups" you use
> > > > the exclusive version of backup command. Is it a mistake or not?
> > >
> > > Yes, that's true.
> >
> > Well, technically it is *correct*. It's just rather silly that we are using the deprecated API in the example.
> >
> > > How about the attached patch?
> > > Perhaps that is too complicated, but I have no idea how to make it simpler.
> >
> > For this example, can't we just show two sessions. That is, "in a psql, run pg_start_backup().
> > Then in a different session, copy all the files, and then back in psql run pg_stop_backup()" or such?
> >
> > This is still just an example of a low level operation, where the recommendation is (and is there iirc)
> > to use a different tool for it already.
>
> I thought the point of the example is to show a workable script that could
> perform a backup and could be used as a starting point to develop your own
> backup solution. (I know that there are people who think writing your own
> backup solution is evil, but I am not one of them.)
That's certainly not actually the case. We don't currently have
anywhere close to sufficient documention (unless you are reading the
code and understand how PG works) for someone to develop their own
backup solution using the low-level API. There's been attempts to fix
that, and I suspect there'll be another attempt to improve the situation
for v14, but not sure if that'll be successful.
> If we replace that with a verbal description of how to do it, the example just
> duplicates what is already documented.
>
> In that case I would opt for simply removing the example.
Removing the example, as it really doesn't do what it implies, is
probably the best way to address this. I'm not convinced that we could
come up with a sufficient verbal description, but I'm happy to take a
look and provide feedback if someone wants to try.
Thanks,
Stephen
Attachments:
signature.asc (application/pgp-signature, 818B) download
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2020-10-07 14:12 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-09-22 14:17 Possible mistake in backup documentation PG Doc comments form <noreply@postgresql.org>
2020-09-25 12:32 ` Laurenz Albe <laurenz.albe@cybertec.at>
2020-09-25 12:50 ` Magnus Hagander <magnus@hagander.net>
2020-09-28 08:50 ` Laurenz Albe <laurenz.albe@cybertec.at>
2020-10-07 14:12 ` Stephen Frost <sfrost@snowman.net>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox