Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cBjok-0005tG-L4 for pgsql-docs@arkaria.postgresql.org; Tue, 29 Nov 2016 14:55:34 +0000 Received: from localhost ([127.0.0.1] helo=postgresql.org) by malur.postgresql.org with smtp (Exim 4.84_2) (envelope-from ) id 1cBjok-00011U-6O for pgsql-docs@arkaria.postgresql.org; Tue, 29 Nov 2016 14:55:34 +0000 Received: from makus.postgresql.org ([2001:4800:1501:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1cBjoN-0000ay-Du for pgsql-docs@postgresql.org; Tue, 29 Nov 2016 14:55:11 +0000 Received: from pro-open.de ([87.106.136.39] helo=www.pro-open.de) by makus.postgresql.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cBjoK-0003QQ-NF for pgsql-docs@postgresql.org; Tue, 29 Nov 2016 14:55:10 +0000 Received: from [192.168.0.135] (aftr-37-201-242-74.unity-media.net [37.201.242.74]) by www.pro-open.de (Postfix) with ESMTP id 244D21045EF3; Tue, 29 Nov 2016 15:55:04 +0100 (CET) Subject: Re: Missing important information in backup.sgml To: Stephen Frost References: <20161116143651.GC13284@tamriel.snowman.net> <80e18b98-9b72-ddee-2a34-76302e5d8a0b@pro-open.de> <20161123204139.GZ13284@tamriel.snowman.net> <18630438-5cf7-ae42-fc51-30770fb43f54@pro-open.de> <20161129134323.GO13284@tamriel.snowman.net> Cc: "pgsql-docs@postgresql.org" , Kevin Grittner From: "Gunnar \"Nick\" Bluth" Message-ID: Date: Tue, 29 Nov 2016 15:54:57 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:45.0) Gecko/20100101 Thunderbird/45.5.0 MIME-Version: 1.0 In-Reply-To: <20161129134323.GO13284@tamriel.snowman.net> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="KNxW35vhJwkaaUr03rxndLNg4pKtkNLXB" X-Pg-Spam-Score: -4.8 (----) List-Archive: List-Help: List-ID: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: X-Mailing-List: pgsql-docs Precedence: bulk Sender: pgsql-docs-owner@postgresql.org This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --KNxW35vhJwkaaUr03rxndLNg4pKtkNLXB From: "Gunnar \"Nick\" Bluth" To: Stephen Frost Cc: "pgsql-docs@postgresql.org" , Kevin Grittner Message-ID: Subject: Re: [DOCS] Missing important information in backup.sgml References: <20161116143651.GC13284@tamriel.snowman.net> <80e18b98-9b72-ddee-2a34-76302e5d8a0b@pro-open.de> <20161123204139.GZ13284@tamriel.snowman.net> <18630438-5cf7-ae42-fc51-30770fb43f54@pro-open.de> <20161129134323.GO13284@tamriel.snowman.net> In-Reply-To: <20161129134323.GO13284@tamriel.snowman.net> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: quoted-printable Am 29.11.2016 um 14:43 schrieb Stephen Frost: > Greetings, >=20 > * Gunnar "Nick" Bluth (gunnar.bluth@pro-open.de) wrote: >> Am 23.11.2016 um 21:41 schrieb Stephen Frost: >>> * Gunnar "Nick" Bluth (gunnar.bluth@pro-open.de) wrote: >>> One of the very important things that should be done as part of a backup >>> is to ensure that all of the archive files required to restore the >>> database to a consistent state are safely stored in the archive. If >>> that isn't done then it's possible that an incomplete archive may also >>> render backups invalid. >> >> Well, the need to have a complete archive is described in the docs >> already. Maybe the potential consequences of an incomplete archive >> should be pointed or more drastically...? >=20 > We should probably add to "step 5" something about "verify that all WAL > files have been archived between the start and stop backup" or similar. +1 >> Now, the main purpose of my patch was to document a behaviour that many >> of us have run into, namely that FATAL error showing up in the log when >> the archive_command exits with RC > 127. It's a nuisance only, but it >> does send people on false tracks and should at least be mentioned in the >> documentation. >=20 > I agree that we should add information to the documentation that certain > error codes are handled differently. >=20 >> And since a couple of people does use rsync (or some wrappers around it) >> for archiving, and that is notoriously giving RCs > 127, it seems legit >> to at least mention it, no? >=20 > The low-level API documentation should be focused on the API and not how > to (mis)use the API using common unix commands. >=20 >> diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml >> index 6eaed1e..a8f574e 100644 >> --- a/doc/src/sgml/backup.sgml >> +++ b/doc/src/sgml/backup.sgml >> @@ -587,7 +587,8 @@ tar -cf backup.tar /usr/local/pgsql/data >> the administrator specify a shell command to be executed to copy a >> completed segment file to wherever it needs to go. The command cou= ld be >> as simple as a cp, or it could invoke a complex shell >> - script — it's all up to you. >> + script — it's all up to you. There however are some things to= consider >> + when creating such a command, most of which are covered below. >> >=20 > If we're changing this then we should remove the notion that it could be > "as simple as a cp" because it really should *not* be. That is a > dangerous and very poor recommendation to be making to our users. That thought creeped on me as well... ;-) >> >> @@ -636,7 +637,11 @@ test ! -f /mnt/server/archivedir/00000001000000A900= 000065 && cp pg_wal/0 >> PostgreSQL will assume that the file has been >> successfully archived, and will remove or recycle it. However, a n= onzero >> status tells PostgreSQL that the file was not archi= ved; >> - it will try again periodically until it succeeds. >> + it will try again periodically until it succeeds. Note that an exit >> + status of 128 or higher will cause the archiver to exit, resulting = in a >> + FATAL error in the server log. It will be restarted by = the >> + postmaster and continue where it left. E.g., rsync is k= nown >> + for returning exit statuses of 255 on network issues. >> >=20 > I agree with adding documentation about what happens with different exit > status values. I don't believe we should make any mention of rsync. A > sophisticated enough user to understand exit codes should be able to > work out what the exit code is for whatever tool or tools they're using, > it's not on us to document what the exit codes are for every possible > tool (nor should one even use something as simple as a bare cp or rsync > in archive_command). Fair enough. >=20 >> >> @@ -696,6 +701,16 @@ test ! -f /mnt/server/archivedir/00000001000000A900= 000065 && cp pg_wal/0 >> preserve the file name (%f). >> >>=20=20 >> + >> + Depending on your specific requirements (and datacenter layout), yo= u may >> + want to make sure that the archived WAL segments have been written = out to >> + persistent storage before the archive_command returns. >> + Otherwise, a WAL segment that is assumed by PostgreSQL= >> + to be archived could be recycled or removed prematurely, rendering = your >> + archive incomplete (and thus disabling a recovery) in case of an ou= tage of >> + the archiving destination. >> + >=20 > I dislike the tone of this. The wording I would suggest would be more > along the lines of: >=20 > The archive_command should only return success once the WAL segment has > been completely copied, written out, and synced to persistent storage as > PostgreSQL will recycle or remove the segment shortly after the > archive_command returns. If the WAL segment is lost due to an outage of > the archive server or other issue, any backup which was performed during > the time that the WAL segment was written will be unusable and > Point-In-Time-Recovery from an earlier backup will not be usable past > the missing WAL segment. Sounds good to me. I'll incorparate that and send -v6 soon! --=20 Gunnar "Nick" Bluth RHCE/SCLA Mobil +49 172 8853339 Email: gunnar.bluth@pro-open.de _____________________________________________________________ In 1984 mainstream users were choosing VMS over UNIX. Ten years later they are choosing Windows over UNIX. What part of that message aren't you getting? - Tom Payne --KNxW35vhJwkaaUr03rxndLNg4pKtkNLXB Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQEcBAEBCAAGBQJYPZbGAAoJEBAQrmsyiTOMLeUH/0+f8tC3iXhbOS0TEG6K3OtF chADy+F/lh+/KOBt3kuXsKr4toB8cciefFsrQkZ89A6gj/rLcyqJSpHIQuo1dcMR sF3pTfnmZJ44Z1pO3R/orClcNocVqHCNh5/Jqx6F15EH00CcFw3o5GQtwDJWirM8 o7YKKqmSWkar9ZzDbmMuo8WJ6eP8c1Ko+Gjakj92C3F4d5we2E+mrHJTyinPmtu6 dpXU++1TnDLEtdk3PwrpS2WF3mV2XD+XCOEw/j5pZxTmtwivH9UEtaqx2oC8TNwe /fi6KJqV+HvSeoTEmSs5HaUsvCIaf25FDCRRs5H3Sx03lyRkb8cC2NugSCGICxc= =/vXR -----END PGP SIGNATURE----- --KNxW35vhJwkaaUr03rxndLNg4pKtkNLXB--