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
From 0ce2de70811ced07eb75215197cbb83cd7a7d2b9 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.a...@cybertec.at>
Date: Tue, 18 May 2021 19:42:55 +0200
Subject: [PATCH] Improve doc for pg_upgrade and standby servers
Recommend using the --relative option of rsync for clarity
and adapt the code samples accordingly.
Using relative paths makes clearer what is meant by "current
directory" and "remote_dir".
---
doc/src/sgml/ref/pgupgrade.sgml | 20 ++++++++++----------
1 file changed, 10 insertions(+), 10 deletions(-)
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index a83c63cd98..f3d6df8877 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -528,26 +528,26 @@ pg_upgrade.exe
<para>
When using link mode, standby servers can be quickly upgraded using
- <application>rsync</application>. To accomplish this, from a directory on
+ <application>rsync</application>. To accomplish this, change into a directory on
the primary server that is above the old and new database cluster
- directories, run this on the <emphasis>primary</emphasis> for each standby
+ directories and run this on the <emphasis>primary</emphasis> for each standby
server:
<programlisting>
-rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir
+rsync --archive --delete --hard-links --size-only --no-inc-recursive --relative old_cluster new_cluster remote_dir
</programlisting>
where <option>old_cluster</option> and <option>new_cluster</option> are relative
to the current directory on the primary, and <option>remote_dir</option>
- is <emphasis>above</emphasis> the old and new cluster directories
- on the standby. The directory structure under the specified
- directories on the primary and standbys must match. Consult the
+ is the directory on the standby that corresponds to your current directory
+ on the primary. The directory structure under the specified
+ directories on the primary and standbys must be the same. Consult the
<application>rsync</application> manual page for details on specifying the
remote directory, e.g.,
<programlisting>
-rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/9.5 \
- /opt/PostgreSQL/9.6 standby.example.com:/opt/PostgreSQL
+rsync --archive --delete --hard-links --size-only --no-inc-recursive --relative 9.6 13 \
+ standby.example.com:/var/lib/postgresql
</programlisting>
You can verify what the command will do using
@@ -576,8 +576,8 @@ rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/Postgr
<application>rsync</application> command for each tablespace directory, e.g.:
<programlisting>
-rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_9.5_201510051 \
- /vol1/pg_tblsp/PG_9.6_201608131 standby.example.com:/vol1/pg_tblsp
+rsync --archive --delete --hard-links --size-only --no-inc-recursive --relative \
+ PG_9.6_201608131 PG_13_202007201 standby.example.com:/vol1/tblsp
</programlisting>
If you have relocated <filename>pg_wal</filename> outside the data
--
2.26.3
