Date: Wed, 7 Oct 2020 10:12:06 -0400
From: Stephen Frost <sfrost@snowman.net>
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: Magnus Hagander <magnus@hagander.net>, abo@velvica.com,
	Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: Possible mistake in backup documentation
Message-ID: <20201007141206.GZ3063@tamriel.snowman.net>
References: <160078426053.14061.808669930112439771@wrigleys.postgresql.org>
 <3e33df71449fdc083b1ed8a4dfe3ee129de59798.camel@cybertec.at>
 <CABUevEzRrW5M8aiw0bho8_keekc1hzksn8N6nCGacgTP_x7pTQ@mail.gmail.com>
 <65ee31c337b0b832a21524f13e14ea8b2e475ac1.camel@cybertec.at>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
	protocol="application/pgp-signature"; boundary="/cFG30PKHi9lwv6o"
Content-Disposition: inline
In-Reply-To: <65ee31c337b0b832a21524f13e14ea8b2e475ac1.camel@cybertec.at>
User-Agent: Mutt/1.5.24 (2015-08-30)
Precedence: bulk


--/cFG30PKHi9lwv6o
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

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 i=
t is now
> > > > recommended that all users upgrade their scripts to use non-exclusi=
ve
> > > > 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?
> > >=20
> > > Yes, that's true.
> >=20
> > Well, technically it is *correct*. It's just rather silly that we are u=
sing the deprecated API in the example.
> >=20
> > > How about the attached patch?
> > > Perhaps that is too complicated, but I have no idea how to make it si=
mpler.
> >=20
> > 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?
> >=20
> > This is still just an example of a low level operation, where the recom=
mendation is (and is there iirc)
> >  to use a different tool for it already.
>=20
> 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.
>=20
> 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

--/cFG30PKHi9lwv6o
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQIcBAEBCgAGBQJffcy2AAoJEO1sijiDR2RVQKMQAI0lhdOxcL1fLU771nUJSSsv
7nD+rfunPekG6VckNm1tllIOpOT3pVGuUp87lQk14wGT9NHBoqZt+dukZJRYgZuI
eZNFuS8RkW7x7wGmglqwKkvw/579pU+jCoCcco+5iguqEcZ+imbFaCixrbD2gRM+
J/wr+SVR7/8WSB5XkcU2e08WkpYCnKJ0N1VmZMLjJUAUAufInq6ATu8hbuRXJne7
k4ZlfW7nMEcZNdJ0PhsgiOc+gVrHHcXlu8NqtAF2ZSj7We2goj/DIUpkCkXMbc46
DU7fp+tEilX/rdYSIVHX9jl0sq0DXxiqybdvs8HaGwnhkSvGv7w9BvnhnImV1B5R
RsRZwIbnq6FS4LQ7F+KdefQeOYHACDc6CO+J0JlXSdkq6g7SFQRoVmrUDbLs5/Hw
f/zkyNE6Ia9sikZvVNUoTw1GTPOKy7lUdvm06BoEHd+wUUMrQy1nWA1MqhFtBVuM
d8hFctBUKBGZ2z1N+4YWDrSUK4BbRHzs1LIvFPmU19pE7zCcQ/g7JpSuKu8oevus
rhhNvc8m+QQ0fxcuoCbP8taOHERqWyPsVB6lo3S8IDlaIecrTT37WTgKQ4ihHnrq
cpgCBn4wwwDhHmhsp8wASaw9J7kMJ+K54pVhdaCUj+MhKCnWU/clBSNTKV1rchNj
Zf2DXuA8jxc3ipy7njhy
=WpnD
-----END PGP SIGNATURE-----

--/cFG30PKHi9lwv6o--