Skip to content

Commit 417f78a

Browse files
bmomjianbmomjian
committed
pg_upgrade: document use of rsync for slave upgrades
Also document that rsync has one-second granularity for file change comparisons. Report by Stephen Frost
1 parent 13dbc7a commit 417f78a

File tree

2 files changed

+152
-13
lines changed

2 files changed

+152
-13
lines changed

‎doc/src/sgml/backup.sgml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -438,8 +438,10 @@ tar -cf backup.tar /usr/local/pgsql/data
438438
Another option is to use <application>rsync</> to perform a file
439439
system backup. This is done by first running <application>rsync</>
440440
while the database server is running, then shutting down the database
441-
server just long enough to do a second <application>rsync</>. The
442-
second <application>rsync</> will be much quicker than the first,
441+
server long enough to do an <command>rsync --checksum</>.
442+
(<option>--checksum</> is necessary because <command>rsync</> only
443+
has file modification-time granularity of one second.) The
444+
second <application>rsync</> will be quicker than the first,
443445
because it has relatively little data to transfer, and the end result
444446
will be consistent because the server was down. This method
445447
allows a file system backup to be performed with minimal downtime.

‎doc/src/sgml/pgupgrade.sgml

Lines changed: 148 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,11 @@ NET STOP postgresql-8.4
315315
NET STOP postgresql-9.0
316316
</programlisting>
317317
</para>
318+
319+
<para>
320+
Streaming replication and log-shipping standby servers can remain running until
321+
a later step.
322+
</para>
318323
</step>
319324

320325
<step>
@@ -398,6 +403,136 @@ pg_upgrade.exe
398403
</para>
399404
</step>
400405

406+
<step>
407+
<title>Upgrade Streaming Replication and Log-Shipping standby
408+
servers</title>
409+
410+
<para>
411+
If you have Streaming Replication (<xref
412+
linkend="streaming-replication">) or Log-Shipping (<xref
413+
linkend="warm-standby">) standby servers, follow these steps to
414+
upgrade them (before starting any servers):
415+
</para>
416+
417+
<procedure>
418+
419+
<step>
420+
<title>Install the new PostgreSQL binaries on standby servers</title>
421+
422+
<para>
423+
Make sure the new binaries and support files are installed on all
424+
standby servers.
425+
</para>
426+
</step>
427+
428+
<step>
429+
<title>Make sure the new standby data directories do <emphasis>not</>
430+
exist</title>
431+
432+
<para>
433+
Make sure the new standby data directories do <emphasis>not</>
434+
exist or are empty. If <application>initdb</> was run, delete
435+
the standby server data directories.
436+
</para>
437+
</step>
438+
439+
<step>
440+
<title>Install custom shared object files</title>
441+
442+
<para>
443+
Install the same custom shared object files on the new standbys
444+
that you installed in the new master cluster.
445+
</para>
446+
</step>
447+
448+
<step>
449+
<title>Stop standby servers</title>
450+
451+
<para>
452+
If the standby servers are still running, stop them now using the
453+
above instructions.
454+
</para>
455+
</step>
456+
457+
<step>
458+
<title>Verify standby servers</title>
459+
460+
<para>
461+
To prevent old standby servers from being modified, run
462+
<application>pg_controldata</> against the primary and standby
463+
clusters and verify that the <quote>Latest checkpoint location</>
464+
values match in all clusters. (This requires the standbys to be
465+
shut down after the primary.)
466+
</para>
467+
</step>
468+
469+
<step>
470+
<title>Save configuration files</title>
471+
472+
<para>
473+
Save any configuration files from the standbys you need to keep,
474+
e.g. <filename>postgresql.conf</>, <literal>recovery.conf</>,
475+
as these will be overwritten or removed in the next step.
476+
</para>
477+
</step>
478+
479+
<step>
480+
<title>Start and stop the new master cluster</title>
481+
482+
<para>
483+
In the new master cluster, change <varname>wal_level</> to
484+
<literal>hot_standby</> in the <filename>postgresql.conf</> file
485+
and then start and stop the cluster.
486+
</para>
487+
</step>
488+
489+
<step>
490+
<title>Run <application>rsync</></title>
491+
492+
<para>
493+
From a directory that is above the old and new database cluster
494+
directories, run this for each slave:
495+
496+
<programlisting>
497+
rsync --archive --delete --hard-links --size-only old_pgdata new_pgdata remote_dir
498+
</programlisting>
499+
500+
where <option>old_pgdata</> and <option>new_pgdata</> are relative
501+
to the current directory, and <option>remote_dir</> is
502+
<emphasis>above</> the old and new cluster directories on
503+
the standby server. The old and new relative cluster paths
504+
must match on the master and standby server. Consult the
505+
<application>rsync</> manual page for details on specifying the
506+
remote directory, e.g. <literal>standbyhost:/opt/PostgreSQL/</>.
507+
<application>rsync</> will be fast when <application>pg_upgrade</>'s
508+
<option>--link</> mode is used because it will create hard links
509+
on the remote server rather than transferring user data.
510+
</para>
511+
512+
<para>
513+
If you have tablespaces, you will need to run a similar
514+
<application>rsync</> command for each tablespace directory. If you
515+
have relocated <filename>pg_xlog</> outside the data directories,
516+
<application>rsync</> must be run on those directories too.
517+
</para>
518+
</step>
519+
520+
<step>
521+
<title>Configure streaming replication and log-shipping standby
522+
servers</title>
523+
524+
<para>
525+
Configure the servers for log shipping. (You do not need to run
526+
<function>pg_start_backup()</> and <function>pg_stop_backup()</>
527+
or take a file system backup as the slaves are still synchronized
528+
with the master.)
529+
</para>
530+
</step>
531+
532+
</procedure>
533+
534+
</step>
535+
401536
<step>
402537
<title>Restore <filename>pg_hba.conf</></title>
403538

@@ -408,6 +543,15 @@ pg_upgrade.exe
408543
</para>
409544
</step>
410545

546+
<step>
547+
<title>Start the new server</title>
548+
549+
<para>
550+
The new server can now be safely started, and then any
551+
<application>rsync</>'ed standby servers.
552+
</para>
553+
</step>
554+
411555
<step>
412556
<title>Post-Upgrade processing</title>
413557

@@ -547,23 +691,16 @@ psql --username postgres --file script.sql postgres
547691
location. (This is not relevant on Windows.)
548692
</para>
549693

550-
<para>
551-
A Log-Shipping Standby Server (<xref linkend="warm-standby">) cannot
552-
be upgraded because the server must allow writes. The simplest way
553-
is to upgrade the primary and use <command>rsync</> to rebuild the
554-
standbys. You can run <command>rsync</> while the primary is down,
555-
or as part of a base backup (<xref linkend="backup-base-backup">)
556-
which overwrites the old standby cluster.
557-
</para>
558-
559694
<para>
560695
If you want to use link mode and you do not want your old cluster
561696
to be modified when the new cluster is started, make a copy of the
562697
old cluster and upgrade that in link mode. To make a valid copy
563698
of the old cluster, use <command>rsync</> to create a dirty
564699
copy of the old cluster while the server is running, then shut down
565-
the old server and run <command>rsync</> again to update the copy with any
566-
changes to make it consistent. You might want to exclude some
700+
the old server and run <command>rsync --checksum</> again to update the
701+
copy with any changes to make it consistent. (<option>--checksum</>
702+
is necessary because <command>rsync</> only has file modification-time
703+
granularity of one second.) You might want to exclude some
567704
files, e.g. <filename>postmaster.pid</>, as documented in <xref
568705
linkend="backup-lowlevel-base-backup">. If your file system supports
569706
file system snapshots or copy-on-write file copies, you can use that

0 commit comments

Comments
 (0)