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.

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
        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
-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
        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.,
-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
        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.:
-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
        If you have relocated <filename>pg_wal</filename> outside the data

Reply via email to