Message-ID: <65ee31c337b0b832a21524f13e14ea8b2e475ac1.camel@cybertec.at>
Subject: Re: Possible mistake in backup documentation
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Magnus Hagander <magnus@hagander.net>
Cc: abo@velvica.com, Pg Docs <pgsql-docs@lists.postgresql.org>
Date: Mon, 28 Sep 2020 10:50:57 +0200
In-Reply-To: 
 <CABUevEzRrW5M8aiw0bho8_keekc1hzksn8N6nCGacgTP_x7pTQ@mail.gmail.com>
References: <160078426053.14061.808669930112439771@wrigleys.postgresql.org>
	 <3e33df71449fdc083b1ed8a4dfe3ee129de59798.camel@cybertec.at>
	 <CABUevEzRrW5M8aiw0bho8_keekc1hzksn8N6nCGacgTP_x7pTQ@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
User-Agent: Evolution 3.36.5 (3.36.5-1.fc32) 
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Precedence: bulk

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