Message-ID: <22f129004bb66cd91e1dfd3345a9787f5039f3ae.camel@cybertec.at>
Subject: Improve documentation for pg_upgrade, standbys and rsync
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: pgsql-docs@lists.postgresql.org
Date: Tue, 18 May 2021 19:49:45 +0200
Content-Type: multipart/mixed; boundary="=-ofV9USgc/5CFS9Rs7Yn3"
User-Agent: Evolution 3.36.5 (3.36.5-2.fc32) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/22f129004bb66cd91e1dfd3345a9787f5039f3ae.camel%40cybertec.at>
Precedence: bulk


--=-ofV9USgc/5CFS9Rs7Yn3
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: 7bit

I revently tried to upgrade a standby following the documentation,
but I found it hard to understand, and it took me several tries to
get it right.  This is of course owing to my lack of expertise with
rsync, but I think the documentation and examples could be clearer.

I think it would be a good idea to recommend the --relative option
of rsync.

Here is a patch that does that, as well as update the versions in
the code samples to something more recent.  Also, I think it makes
sense to place the data directory in the sample in /var/lib/postgresql,
which is similar to what many people will have in real life.

Yours,
Laurenz Albe

--=-ofV9USgc/5CFS9Rs7Yn3
Content-Disposition: attachment;
	filename="0001-Improve-doc-for-pg_upgrade-and-standby-servers.patch"
Content-Type: text/x-patch;
	name="0001-Improve-doc-for-pg_upgrade-and-standby-servers.patch";
	charset="UTF-8"
Content-Transfer-Encoding: base64

RnJvbSAwY2UyZGU3MDgxMWNlZDA3ZWI3NTIxNTE5N2NiYjgzY2Q3YTdkMmI5IE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiBMYXVyZW56IEFsYmUgPGxhdXJlbnouYWxiZUBjeWJlcnRlYy5h
dD4KRGF0ZTogVHVlLCAxOCBNYXkgMjAyMSAxOTo0Mjo1NSArMDIwMApTdWJqZWN0OiBbUEFUQ0hd
IEltcHJvdmUgZG9jIGZvciBwZ191cGdyYWRlIGFuZCBzdGFuZGJ5IHNlcnZlcnMKClJlY29tbWVu
ZCB1c2luZyB0aGUgLS1yZWxhdGl2ZSBvcHRpb24gb2YgcnN5bmMgZm9yIGNsYXJpdHkKYW5kIGFk
YXB0IHRoZSBjb2RlIHNhbXBsZXMgYWNjb3JkaW5nbHkuClVzaW5nIHJlbGF0aXZlIHBhdGhzIG1h
a2VzIGNsZWFyZXIgd2hhdCBpcyBtZWFudCBieSAiY3VycmVudApkaXJlY3RvcnkiIGFuZCAicmVt
b3RlX2RpciIuCi0tLQogZG9jL3NyYy9zZ21sL3JlZi9wZ3VwZ3JhZGUuc2dtbCB8IDIwICsrKysr
KysrKystLS0tLS0tLS0tCiAxIGZpbGUgY2hhbmdlZCwgMTAgaW5zZXJ0aW9ucygrKSwgMTAgZGVs
ZXRpb25zKC0pCgpkaWZmIC0tZ2l0IGEvZG9jL3NyYy9zZ21sL3JlZi9wZ3VwZ3JhZGUuc2dtbCBi
L2RvYy9zcmMvc2dtbC9yZWYvcGd1cGdyYWRlLnNnbWwKaW5kZXggYTgzYzYzY2Q5OC4uZjNkNmRm
ODg3NyAxMDA2NDQKLS0tIGEvZG9jL3NyYy9zZ21sL3JlZi9wZ3VwZ3JhZGUuc2dtbAorKysgYi9k
b2Mvc3JjL3NnbWwvcmVmL3BndXBncmFkZS5zZ21sCkBAIC01MjgsMjYgKzUyOCwyNiBAQCBwZ191
cGdyYWRlLmV4ZQogCiAgICAgICA8cGFyYT4KICAgICAgICBXaGVuIHVzaW5nIGxpbmsgbW9kZSwg
c3RhbmRieSBzZXJ2ZXJzIGNhbiBiZSBxdWlja2x5IHVwZ3JhZGVkIHVzaW5nCi0gICAgICAgPGFw
cGxpY2F0aW9uPnJzeW5jPC9hcHBsaWNhdGlvbj4uICBUbyBhY2NvbXBsaXNoIHRoaXMsIGZyb20g
YSBkaXJlY3Rvcnkgb24KKyAgICAgICA8YXBwbGljYXRpb24+cnN5bmM8L2FwcGxpY2F0aW9uPi4g
IFRvIGFjY29tcGxpc2ggdGhpcywgY2hhbmdlIGludG8gYSBkaXJlY3Rvcnkgb24KICAgICAgICB0
aGUgcHJpbWFyeSBzZXJ2ZXIgdGhhdCBpcyBhYm92ZSB0aGUgb2xkIGFuZCBuZXcgZGF0YWJhc2Ug
Y2x1c3RlcgotICAgICAgIGRpcmVjdG9yaWVzLCBydW4gdGhpcyBvbiB0aGUgPGVtcGhhc2lzPnBy
aW1hcnk8L2VtcGhhc2lzPiBmb3IgZWFjaCBzdGFuZGJ5CisgICAgICAgZGlyZWN0b3JpZXMgYW5k
IHJ1biB0aGlzIG9uIHRoZSA8ZW1waGFzaXM+cHJpbWFyeTwvZW1waGFzaXM+IGZvciBlYWNoIHN0
YW5kYnkKICAgICAgICBzZXJ2ZXI6CiAKIDxwcm9ncmFtbGlzdGluZz4KLXJzeW5jIC0tYXJjaGl2
ZSAtLWRlbGV0ZSAtLWhhcmQtbGlua3MgLS1zaXplLW9ubHkgLS1uby1pbmMtcmVjdXJzaXZlIG9s
ZF9jbHVzdGVyIG5ld19jbHVzdGVyIHJlbW90ZV9kaXIKK3JzeW5jIC0tYXJjaGl2ZSAtLWRlbGV0
ZSAtLWhhcmQtbGlua3MgLS1zaXplLW9ubHkgLS1uby1pbmMtcmVjdXJzaXZlIC0tcmVsYXRpdmUg
b2xkX2NsdXN0ZXIgbmV3X2NsdXN0ZXIgcmVtb3RlX2RpcgogPC9wcm9ncmFtbGlzdGluZz4KIAog
ICAgICAgIHdoZXJlIDxvcHRpb24+b2xkX2NsdXN0ZXI8L29wdGlvbj4gYW5kIDxvcHRpb24+bmV3
X2NsdXN0ZXI8L29wdGlvbj4gYXJlIHJlbGF0aXZlCiAgICAgICAgdG8gdGhlIGN1cnJlbnQgZGly
ZWN0b3J5IG9uIHRoZSBwcmltYXJ5LCBhbmQgPG9wdGlvbj5yZW1vdGVfZGlyPC9vcHRpb24+Ci0g
ICAgICAgaXMgPGVtcGhhc2lzPmFib3ZlPC9lbXBoYXNpcz4gdGhlIG9sZCBhbmQgbmV3IGNsdXN0
ZXIgZGlyZWN0b3JpZXMKLSAgICAgICBvbiB0aGUgc3RhbmRieS4gIFRoZSBkaXJlY3Rvcnkgc3Ry
dWN0dXJlIHVuZGVyIHRoZSBzcGVjaWZpZWQKLSAgICAgICBkaXJlY3RvcmllcyBvbiB0aGUgcHJp
bWFyeSBhbmQgc3RhbmRieXMgbXVzdCBtYXRjaC4gIENvbnN1bHQgdGhlCisgICAgICAgaXMgdGhl
IGRpcmVjdG9yeSBvbiB0aGUgc3RhbmRieSB0aGF0IGNvcnJlc3BvbmRzIHRvIHlvdXIgY3VycmVu
dCBkaXJlY3RvcnkKKyAgICAgICBvbiB0aGUgcHJpbWFyeS4gIFRoZSBkaXJlY3Rvcnkgc3RydWN0
dXJlIHVuZGVyIHRoZSBzcGVjaWZpZWQKKyAgICAgICBkaXJlY3RvcmllcyBvbiB0aGUgcHJpbWFy
eSBhbmQgc3RhbmRieXMgbXVzdCBiZSB0aGUgc2FtZS4gIENvbnN1bHQgdGhlCiAgICAgICAgPGFw
cGxpY2F0aW9uPnJzeW5jPC9hcHBsaWNhdGlvbj4gbWFudWFsIHBhZ2UgZm9yIGRldGFpbHMgb24g
c3BlY2lmeWluZyB0aGUKICAgICAgICByZW1vdGUgZGlyZWN0b3J5LCBlLmcuLAogCiA8cHJvZ3Jh
bWxpc3Rpbmc+Ci1yc3luYyAtLWFyY2hpdmUgLS1kZWxldGUgLS1oYXJkLWxpbmtzIC0tc2l6ZS1v
bmx5IC0tbm8taW5jLXJlY3Vyc2l2ZSAvb3B0L1Bvc3RncmVTUUwvOS41IFwKLSAgICAgIC9vcHQv
UG9zdGdyZVNRTC85LjYgc3RhbmRieS5leGFtcGxlLmNvbTovb3B0L1Bvc3RncmVTUUwKK3JzeW5j
IC0tYXJjaGl2ZSAtLWRlbGV0ZSAtLWhhcmQtbGlua3MgLS1zaXplLW9ubHkgLS1uby1pbmMtcmVj
dXJzaXZlIC0tcmVsYXRpdmUgOS42IDEzIFwKKyAgICAgIHN0YW5kYnkuZXhhbXBsZS5jb206L3Zh
ci9saWIvcG9zdGdyZXNxbAogPC9wcm9ncmFtbGlzdGluZz4KIAogICAgICAgIFlvdSBjYW4gdmVy
aWZ5IHdoYXQgdGhlIGNvbW1hbmQgd2lsbCBkbyB1c2luZwpAQCAtNTc2LDggKzU3Niw4IEBAIHJz
eW5jIC0tYXJjaGl2ZSAtLWRlbGV0ZSAtLWhhcmQtbGlua3MgLS1zaXplLW9ubHkgLS1uby1pbmMt
cmVjdXJzaXZlIC9vcHQvUG9zdGdyCiAgICAgICAgPGFwcGxpY2F0aW9uPnJzeW5jPC9hcHBsaWNh
dGlvbj4gY29tbWFuZCBmb3IgZWFjaCB0YWJsZXNwYWNlIGRpcmVjdG9yeSwgZS5nLjoKIAogPHBy
b2dyYW1saXN0aW5nPgotcnN5bmMgLS1hcmNoaXZlIC0tZGVsZXRlIC0taGFyZC1saW5rcyAtLXNp
emUtb25seSAtLW5vLWluYy1yZWN1cnNpdmUgL3ZvbDEvcGdfdGJsc3AvUEdfOS41XzIwMTUxMDA1
MSBcCi0gICAgICAvdm9sMS9wZ190YmxzcC9QR185LjZfMjAxNjA4MTMxIHN0YW5kYnkuZXhhbXBs
ZS5jb206L3ZvbDEvcGdfdGJsc3AKK3JzeW5jIC0tYXJjaGl2ZSAtLWRlbGV0ZSAtLWhhcmQtbGlu
a3MgLS1zaXplLW9ubHkgLS1uby1pbmMtcmVjdXJzaXZlIC0tcmVsYXRpdmUgXAorICAgICAgUEdf
OS42XzIwMTYwODEzMSBQR18xM18yMDIwMDcyMDEgc3RhbmRieS5leGFtcGxlLmNvbTovdm9sMS90
YmxzcAogPC9wcm9ncmFtbGlzdGluZz4KIAogICAgICAgIElmIHlvdSBoYXZlIHJlbG9jYXRlZCA8
ZmlsZW5hbWU+cGdfd2FsPC9maWxlbmFtZT4gb3V0c2lkZSB0aGUgZGF0YQotLSAKMi4yNi4zCgo=


--=-ofV9USgc/5CFS9Rs7Yn3--