Skip to content

Commit f0f46ed

Browse files
tglsfdctglsfdc
committed
Assorted improvements to backup/restore documentation, per Thom Brown.
1 parent 521c26e commit f0f46ed

File tree

1 file changed

+122
-85
lines changed

1 file changed

+122
-85
lines changed

‎doc/src/sgml/backup.sgml

Lines changed: 122 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.156 2010/06/07 02:01:08 itagaki Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.157 2010/08/15 23:04:49 tgl Exp $ -->
22

33
<chapter id="backup">
44
<title>Backup and Restore</title>
@@ -20,7 +20,8 @@
2020
<listitem><para>File system level backup</para></listitem>
2121
<listitem><para>Continuous archiving</para></listitem>
2222
</itemizedlist>
23-
Each has its own strengths and weaknesses; each is discussed in turn below.
23+
Each has its own strengths and weaknesses; each is discussed in turn
24+
in the following sections.
2425
</para>
2526

2627
<sect1 id="backup-dump">
@@ -73,6 +74,16 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
7374
linkend="client-authentication">).
7475
</para>
7576

77+
<para>
78+
An important advantage of <application>pg_dump</> over the other backup
79+
methods described later is that <application>pg_dump</>'s output can
80+
generally be re-loaded into newer versions of <productname>PostgreSQL</>,
81+
whereas file-level backups and continuous archiving are both extremely
82+
server-version-specific. <application>pg_dump</> is also the only method
83+
that will work when transferring a database to a different machine
84+
architecture, such as going from a 32-bit to a 64-bit server.
85+
</para>
86+
7687
<para>
7788
Dumps created by <application>pg_dump</> are internally consistent,
7889
meaning, the dump represents a snapshot of the database at the time
@@ -490,7 +501,7 @@ tar -cf backup.tar /usr/local/pgsql/data
490501
<application>pg_dumpall</application> do not produce file-system-level
491502
backups and cannot be used as part of a continuous-archiving solution.
492503
Such dumps are <emphasis>logical</> and do not contain enough
493-
information to used by WAL reply.
504+
information to be used by WAL replay.
494505
</para>
495506
</note>
496507

@@ -1373,12 +1384,12 @@ archive_command = 'local_backup_script.sh'
13731384

13741385
<para>
13751386
<productname>PostgreSQL</> major versions are represented by the
1376-
first two digit groups of the version number, e.g. 8.4.
1387+
first two digit groups of the version number, e.g., 8.4.
13771388
<productname>PostgreSQL</> minor versions are represented by the
1378-
the third group of version digits, i.e., 8.4.2 is the second minor
1389+
third group of version digits, e.g., 8.4.2 is the second minor
13791390
release of 8.4. Minor releases never change the internal storage
13801391
format and are always compatible with earlier and later minor
1381-
releases of the same major version number, i.e. 8.4.2 is compatible
1392+
releases of the same major version number, e.g., 8.4.2 is compatible
13821393
with 8.4, 8.4.1 and 8.4.6. To update between compatible versions,
13831394
you simply replace the executables while the server is down and
13841395
restart the server. The data directory remains unchanged &mdash;
@@ -1387,14 +1398,86 @@ archive_command = 'local_backup_script.sh'
13871398

13881399
<para>
13891400
For <emphasis>major</> releases of <productname>PostgreSQL</>, the
1390-
internal data storage format is subject to change. When migrating
1391-
data from one major version of <productname>PostgreSQL</> to another,
1392-
you need to back up your data and restore it on the new server.
1393-
This must be done using <application>pg_dump</>; file system level
1394-
backup methods will not work. There are checks in place that prevent
1401+
internal data storage format is subject to change, thus complicating
1402+
upgrades. The traditional method for moving data to a new major version
1403+
is to dump and reload the database. Other, less-well-tested possibilities
1404+
are available, as discussed below.
1405+
</para>
1406+
1407+
<para>
1408+
New major versions also typically introduce some user-visible
1409+
incompatibilities, so application programming changes may be required.
1410+
Cautious users will want to test their client applications on the new
1411+
version before switching over fully; therefore, it's often a good idea to
1412+
set up concurrent installations of old and new versions. When
1413+
testing a <productname>PostgreSQL</> major upgrade, consider the
1414+
following categories of possible changes:
1415+
</para>
1416+
1417+
<variablelist>
1418+
1419+
<varlistentry>
1420+
<term>Administration</term>
1421+
<listitem>
1422+
<para>
1423+
The capabilities available for administrators to monitor and control
1424+
the server often change and improve in each major release.
1425+
</para>
1426+
</listitem>
1427+
</varlistentry>
1428+
1429+
<varlistentry>
1430+
<term>SQL</term>
1431+
<listitem>
1432+
<para>
1433+
Typically this includes new SQL command capabilities and not changes
1434+
in behavior, unless specifically mentioned in the release notes.
1435+
</para>
1436+
</listitem>
1437+
</varlistentry>
1438+
1439+
<varlistentry>
1440+
<term>Library API</term>
1441+
<listitem>
1442+
<para>
1443+
Typically libraries like <application>libpq</> only add new
1444+
functionality, again unless mentioned in the release notes.
1445+
</para>
1446+
</listitem>
1447+
</varlistentry>
1448+
1449+
<varlistentry>
1450+
<term>System Catalogs</term>
1451+
<listitem>
1452+
<para>
1453+
System catalog changes usually only affect database management tools.
1454+
</para>
1455+
</listitem>
1456+
</varlistentry>
1457+
1458+
<varlistentry>
1459+
<term>Server C-language API</term>
1460+
<listitem>
1461+
<para>
1462+
This involves changes in the backend function API, which is written
1463+
in the C programming language. Such changes affect code that
1464+
references backend functions deep inside the server.
1465+
</para>
1466+
</listitem>
1467+
</varlistentry>
1468+
1469+
</variablelist>
1470+
1471+
<sect2 id="migration-methods-pgdump">
1472+
<title>Migrating data via <application>pg_dump</></title>
1473+
1474+
<para>
1475+
To dump data from one major version of <productname>PostgreSQL</> and
1476+
reload it in another, you must use <application>pg_dump</>; file system
1477+
level backup methods will not work. (There are checks in place that prevent
13951478
you from using a data directory with an incompatible version of
1396-
<productname>PostgreSQL</productname>, so no great harm can be done
1397-
by trying to start the wrong server version on a data directory.
1479+
<productname>PostgreSQL</productname>, so no great harm can be done by
1480+
trying to start the wrong server version on a data directory.)
13981481
</para>
13991482

14001483
<para>
@@ -1414,26 +1497,15 @@ archive_command = 'local_backup_script.sh'
14141497
pg_dumpall -p 5432 | psql -d postgres -p 6543
14151498
</programlisting>
14161499

1417-
to transfer your data. Or use an intermediate file if you wish.
1500+
to transfer your data. Or you can use an intermediate file if you wish.
14181501
Then you can shut down the old server and start the new server using
14191502
the port the old one was running on. You should make sure that the
14201503
old database is not updated after you begin to run
1421-
<application>pg_dumpall</>, otherwise you will lose that data. See <xref
1422-
linkend="client-authentication"> for information on how to prohibit
1504+
<application>pg_dumpall</>, otherwise you will lose those updates. See
1505+
<xref linkend="client-authentication"> for information on how to prohibit
14231506
access.
14241507
</para>
14251508

1426-
<para>
1427-
It is also possible to use replication methods, such as
1428-
<productname>Slony</>, to create a standby server with the updated version of
1429-
<productname>PostgreSQL</>. The standby can be on the same computer or
1430-
a different computer. Once it has synced up with the master server
1431-
(running the older version of <productname>PostgreSQL</>), you can
1432-
switch masters and make the standby the master and shut down the older
1433-
database instance. Such a switch-over results in only several seconds
1434-
of downtime for an upgrade.
1435-
</para>
1436-
14371509
<para>
14381510
If you cannot or do not want to run two servers in parallel, you can
14391511
do the backup step before installing the new version, bring down
@@ -1474,68 +1546,33 @@ psql -f backup postgres
14741546
moving an installation like this will not work.)
14751547
</para>
14761548
</note>
1549+
</sect2>
1550+
1551+
<sect2 id="migration-methods-other">
1552+
<title>Other data migration methods</title>
14771553

14781554
<para>
1479-
In practice you probably want to test your client applications on the
1480-
new version before switching over completely. This is another reason
1481-
for setting up concurrent installations of old and new versions. When
1482-
testing a <productname>PostgreSQL</> major upgrade, consider the
1483-
following categories of possible changes:
1555+
The <filename>contrib</> program
1556+
<link linkend="pgupgrade"><application>pg_upgrade</application></link>
1557+
allows an installation to be migrated in-place from one major
1558+
<productname>PostgreSQL</> version to the next. Keep in mind that this
1559+
method does not provide any scope for running old and new versions
1560+
concurrently. Also, <application>pg_upgrade</application> is much less
1561+
battle-tested than <application>pg_dump</application>, so having an
1562+
up-to-date backup is strongly recommended in case something goes wrong.
14841563
</para>
14851564

1486-
<variablelist>
1487-
1488-
<varlistentry>
1489-
<term>Administration</term>
1490-
<listitem>
1491-
<para>
1492-
The capabilities available for administrators to monitor and control
1493-
the server often change and improve in each major release.
1494-
</para>
1495-
</listitem>
1496-
</varlistentry>
1497-
1498-
<varlistentry>
1499-
<term>SQL</term>
1500-
<listitem>
1501-
<para>
1502-
Typically this includes new SQL command capabilities and not changes
1503-
in behavior, unless specifically mentioned in the release notes.
1504-
</para>
1505-
</listitem>
1506-
</varlistentry>
1507-
1508-
<varlistentry>
1509-
<term>Library API</term>
1510-
<listitem>
1511-
<para>
1512-
Typically libraries like <application>libpq</> only add new
1513-
functionality, again unless mentioned in the release notes.
1514-
</para>
1515-
</listitem>
1516-
</varlistentry>
1517-
1518-
<varlistentry>
1519-
<term>System Catalogs</term>
1520-
<listitem>
1521-
<para>
1522-
System catalog changes usually only affect database management tools.
1523-
</para>
1524-
</listitem>
1525-
</varlistentry>
1526-
1527-
<varlistentry>
1528-
<term>Server C-language API</term>
1529-
<listitem>
1530-
<para>
1531-
This involved changes in the backend function API, which is written
1532-
in the C programming language. Such changes effect code that
1533-
references backend functions deep inside the server.
1534-
</para>
1535-
</listitem>
1536-
</varlistentry>
1537-
1538-
</variablelist>
1565+
<para>
1566+
It is also possible to use certain replication methods, such as
1567+
<productname>Slony</>, to create a standby server with the updated version of
1568+
<productname>PostgreSQL</>. The standby can be on the same computer or
1569+
a different computer. Once it has synced up with the master server
1570+
(running the older version of <productname>PostgreSQL</>), you can
1571+
switch masters and make the standby the master and shut down the older
1572+
database instance. Such a switch-over results in only several seconds
1573+
of downtime for an upgrade.
1574+
</para>
15391575

1576+
</sect2>
15401577
</sect1>
15411578
</chapter>

0 commit comments

Comments
 (0)