Assorted improvements to backup/restore documentation, per Thom Brown.
This commit is contained in:
Tom Lane
parent
521c26ebf7
commit
f0f46ed66a
@ -1,4 +1,4 @@
|
||||
<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.156 2010/06/07 02:01:08 itagaki Exp $ -->
|
||||
<!-- $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.157 2010/08/15 23:04:49 tgl Exp $ -->
|
||||
|
||||
<chapter id="backup">
|
||||
<title>Backup and Restore</title>
|
||||
@ -20,7 +20,8 @@
|
||||
<listitem><para>File system level backup</para></listitem>
|
||||
<listitem><para>Continuous archiving</para></listitem>
|
||||
</itemizedlist>
|
||||
Each has its own strengths and weaknesses; each is discussed in turn below.
|
||||
Each has its own strengths and weaknesses; each is discussed in turn
|
||||
in the following sections.
|
||||
</para>
|
||||
|
||||
<sect1 id="backup-dump">
|
||||
@ -73,6 +74,16 @@ pg_dump <replaceable class="parameter">dbname</replaceable> > <replaceable cl
|
||||
linkend="client-authentication">).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
An important advantage of <application>pg_dump</> over the other backup
|
||||
methods described later is that <application>pg_dump</>'s output can
|
||||
generally be re-loaded into newer versions of <productname>PostgreSQL</>,
|
||||
whereas file-level backups and continuous archiving are both extremely
|
||||
server-version-specific. <application>pg_dump</> is also the only method
|
||||
that will work when transferring a database to a different machine
|
||||
architecture, such as going from a 32-bit to a 64-bit server.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Dumps created by <application>pg_dump</> are internally consistent,
|
||||
meaning, the dump represents a snapshot of the database at the time
|
||||
@ -490,7 +501,7 @@ tar -cf backup.tar /usr/local/pgsql/data
|
||||
<application>pg_dumpall</application> do not produce file-system-level
|
||||
backups and cannot be used as part of a continuous-archiving solution.
|
||||
Such dumps are <emphasis>logical</> and do not contain enough
|
||||
information to used by WAL reply.
|
||||
information to be used by WAL replay.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -1373,12 +1384,12 @@ archive_command = 'local_backup_script.sh'
|
||||
|
||||
<para>
|
||||
<productname>PostgreSQL</> major versions are represented by the
|
||||
first two digit groups of the version number, e.g. 8.4.
|
||||
first two digit groups of the version number, e.g., 8.4.
|
||||
<productname>PostgreSQL</> minor versions are represented by the
|
||||
the third group of version digits, i.e., 8.4.2 is the second minor
|
||||
third group of version digits, e.g., 8.4.2 is the second minor
|
||||
release of 8.4. Minor releases never change the internal storage
|
||||
format and are always compatible with earlier and later minor
|
||||
releases of the same major version number, i.e. 8.4.2 is compatible
|
||||
releases of the same major version number, e.g., 8.4.2 is compatible
|
||||
with 8.4, 8.4.1 and 8.4.6. To update between compatible versions,
|
||||
you simply replace the executables while the server is down and
|
||||
restart the server. The data directory remains unchanged —
|
||||
@ -1387,98 +1398,18 @@ archive_command = 'local_backup_script.sh'
|
||||
|
||||
<para>
|
||||
For <emphasis>major</> releases of <productname>PostgreSQL</>, the
|
||||
internal data storage format is subject to change. When migrating
|
||||
data from one major version of <productname>PostgreSQL</> to another,
|
||||
you need to back up your data and restore it on the new server.
|
||||
This must be done using <application>pg_dump</>; file system level
|
||||
backup methods will not work. There are checks in place that prevent
|
||||
you from using a data directory with an incompatible version of
|
||||
<productname>PostgreSQL</productname>, so no great harm can be done
|
||||
by trying to start the wrong server version on a data directory.
|
||||
internal data storage format is subject to change, thus complicating
|
||||
upgrades. The traditional method for moving data to a new major version
|
||||
is to dump and reload the database. Other, less-well-tested possibilities
|
||||
are available, as discussed below.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is recommended that you use the <application>pg_dump</> and
|
||||
<application>pg_dumpall</> programs from the newer version of
|
||||
<productname>PostgreSQL</>, to take advantage of enhancements
|
||||
that might have been made in these programs. Current releases of the
|
||||
dump programs can read data from any server version back to 7.0.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The least downtime can be achieved by installing the new server in
|
||||
a different directory and running both the old and the new servers
|
||||
in parallel, on different ports. Then you can use something like:
|
||||
|
||||
<programlisting>
|
||||
pg_dumpall -p 5432 | psql -d postgres -p 6543
|
||||
</programlisting>
|
||||
|
||||
to transfer your data. Or use an intermediate file if you wish.
|
||||
Then you can shut down the old server and start the new server using
|
||||
the port the old one was running on. You should make sure that the
|
||||
old database is not updated after you begin to run
|
||||
<application>pg_dumpall</>, otherwise you will lose that data. See <xref
|
||||
linkend="client-authentication"> for information on how to prohibit
|
||||
access.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is also possible to use replication methods, such as
|
||||
<productname>Slony</>, to create a standby server with the updated version of
|
||||
<productname>PostgreSQL</>. The standby can be on the same computer or
|
||||
a different computer. Once it has synced up with the master server
|
||||
(running the older version of <productname>PostgreSQL</>), you can
|
||||
switch masters and make the standby the master and shut down the older
|
||||
database instance. Such a switch-over results in only several seconds
|
||||
of downtime for an upgrade.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you cannot or do not want to run two servers in parallel, you can
|
||||
do the backup step before installing the new version, bring down
|
||||
the old server, move the old version out of the way, install the new
|
||||
version, start the new server, and restore the data. For example:
|
||||
|
||||
<programlisting>
|
||||
pg_dumpall > backup
|
||||
pg_ctl stop
|
||||
mv /usr/local/pgsql /usr/local/pgsql.old
|
||||
# Rename any tablespace directories as well
|
||||
cd ~/postgresql-&version;
|
||||
gmake install
|
||||
initdb -D /usr/local/pgsql/data
|
||||
postgres -D /usr/local/pgsql/data
|
||||
psql -f backup postgres
|
||||
</programlisting>
|
||||
|
||||
See <xref linkend="runtime"> about ways to start and stop the
|
||||
server and other details. The installation instructions will advise
|
||||
you of strategic places to perform these steps.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
When you <quote>move the old installation out of the way</quote>
|
||||
it might no longer be perfectly usable. Some of the executable programs
|
||||
contain absolute paths to various installed programs and data files.
|
||||
This is usually not a big problem, but if you plan on using two
|
||||
installations in parallel for a while you should assign them
|
||||
different installation directories at build time. (This problem
|
||||
is rectified in <productname>PostgreSQL</> version 8.0 and later, so long
|
||||
as you move all subdirectories containing installed files together;
|
||||
for example if <filename>/usr/local/postgres/bin/</> goes to
|
||||
<filename>/usr/local/postgres.old/bin/</>, then
|
||||
<filename>/usr/local/postgres/share/</> must go to
|
||||
<filename>/usr/local/postgres.old/share/</>. In pre-8.0 releases
|
||||
moving an installation like this will not work.)
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
In practice you probably want to test your client applications on the
|
||||
new version before switching over completely. This is another reason
|
||||
for setting up concurrent installations of old and new versions. When
|
||||
New major versions also typically introduce some user-visible
|
||||
incompatibilities, so application programming changes may be required.
|
||||
Cautious users will want to test their client applications on the new
|
||||
version before switching over fully; therefore, it's often a good idea to
|
||||
set up concurrent installations of old and new versions. When
|
||||
testing a <productname>PostgreSQL</> major upgrade, consider the
|
||||
following categories of possible changes:
|
||||
</para>
|
||||
@ -1528,8 +1459,8 @@ psql -f backup postgres
|
||||
<term>Server C-language API</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This involved changes in the backend function API, which is written
|
||||
in the C programming language. Such changes effect code that
|
||||
This involves changes in the backend function API, which is written
|
||||
in the C programming language. Such changes affect code that
|
||||
references backend functions deep inside the server.
|
||||
</para>
|
||||
</listitem>
|
||||
@ -1537,5 +1468,111 @@ psql -f backup postgres
|
||||
|
||||
</variablelist>
|
||||
|
||||
<sect2 id="migration-methods-pgdump">
|
||||
<title>Migrating data via <application>pg_dump</></title>
|
||||
|
||||
<para>
|
||||
To dump data from one major version of <productname>PostgreSQL</> and
|
||||
reload it in another, you must use <application>pg_dump</>; file system
|
||||
level backup methods will not work. (There are checks in place that prevent
|
||||
you from using a data directory with an incompatible version of
|
||||
<productname>PostgreSQL</productname>, so no great harm can be done by
|
||||
trying to start the wrong server version on a data directory.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is recommended that you use the <application>pg_dump</> and
|
||||
<application>pg_dumpall</> programs from the newer version of
|
||||
<productname>PostgreSQL</>, to take advantage of enhancements
|
||||
that might have been made in these programs. Current releases of the
|
||||
dump programs can read data from any server version back to 7.0.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The least downtime can be achieved by installing the new server in
|
||||
a different directory and running both the old and the new servers
|
||||
in parallel, on different ports. Then you can use something like:
|
||||
|
||||
<programlisting>
|
||||
pg_dumpall -p 5432 | psql -d postgres -p 6543
|
||||
</programlisting>
|
||||
|
||||
to transfer your data. Or you can use an intermediate file if you wish.
|
||||
Then you can shut down the old server and start the new server using
|
||||
the port the old one was running on. You should make sure that the
|
||||
old database is not updated after you begin to run
|
||||
<application>pg_dumpall</>, otherwise you will lose those updates. See
|
||||
<xref linkend="client-authentication"> for information on how to prohibit
|
||||
access.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you cannot or do not want to run two servers in parallel, you can
|
||||
do the backup step before installing the new version, bring down
|
||||
the old server, move the old version out of the way, install the new
|
||||
version, start the new server, and restore the data. For example:
|
||||
|
||||
<programlisting>
|
||||
pg_dumpall > backup
|
||||
pg_ctl stop
|
||||
mv /usr/local/pgsql /usr/local/pgsql.old
|
||||
# Rename any tablespace directories as well
|
||||
cd ~/postgresql-&version;
|
||||
gmake install
|
||||
initdb -D /usr/local/pgsql/data
|
||||
postgres -D /usr/local/pgsql/data
|
||||
psql -f backup postgres
|
||||
</programlisting>
|
||||
|
||||
See <xref linkend="runtime"> about ways to start and stop the
|
||||
server and other details. The installation instructions will advise
|
||||
you of strategic places to perform these steps.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
When you <quote>move the old installation out of the way</quote>
|
||||
it might no longer be perfectly usable. Some of the executable programs
|
||||
contain absolute paths to various installed programs and data files.
|
||||
This is usually not a big problem, but if you plan on using two
|
||||
installations in parallel for a while you should assign them
|
||||
different installation directories at build time. (This problem
|
||||
is rectified in <productname>PostgreSQL</> version 8.0 and later, so long
|
||||
as you move all subdirectories containing installed files together;
|
||||
for example if <filename>/usr/local/postgres/bin/</> goes to
|
||||
<filename>/usr/local/postgres.old/bin/</>, then
|
||||
<filename>/usr/local/postgres/share/</> must go to
|
||||
<filename>/usr/local/postgres.old/share/</>. In pre-8.0 releases
|
||||
moving an installation like this will not work.)
|
||||
</para>
|
||||
</note>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="migration-methods-other">
|
||||
<title>Other data migration methods</title>
|
||||
|
||||
<para>
|
||||
The <filename>contrib</> program
|
||||
<link linkend="pgupgrade"><application>pg_upgrade</application></link>
|
||||
allows an installation to be migrated in-place from one major
|
||||
<productname>PostgreSQL</> version to the next. Keep in mind that this
|
||||
method does not provide any scope for running old and new versions
|
||||
concurrently. Also, <application>pg_upgrade</application> is much less
|
||||
battle-tested than <application>pg_dump</application>, so having an
|
||||
up-to-date backup is strongly recommended in case something goes wrong.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is also possible to use certain replication methods, such as
|
||||
<productname>Slony</>, to create a standby server with the updated version of
|
||||
<productname>PostgreSQL</>. The standby can be on the same computer or
|
||||
a different computer. Once it has synced up with the master server
|
||||
(running the older version of <productname>PostgreSQL</>), you can
|
||||
switch masters and make the standby the master and shut down the older
|
||||
database instance. Such a switch-over results in only several seconds
|
||||
of downtime for an upgrade.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user