Skip to content

P
Postgres FD Implementation
Commit f0f46ed6 authored by Tom Lane's avatar Tom Lane
Browse files
Options

Assorted improvements to backup/restore documentation, per Thom Brown.

parent 521c26eb
Hide whitespace changes
Inline Side-by-side
Showing with 122 additions and 85 deletions
doc/src/sgml/backup.sgml
View file @ f0f46ed6
<!-- $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> &gt; <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 &mdash;
......@@ -1387,14 +1398,86 @@ 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
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>
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>
<variablelist>
<varlistentry>
<term>Administration</term>
<listitem>
<para>
The capabilities available for administrators to monitor and control
the server often change and improve in each major release.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SQL</term>
<listitem>
<para>
Typically this includes new SQL command capabilities and not changes
in behavior, unless specifically mentioned in the release notes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Library API</term>
<listitem>
<para>
Typically libraries like <application>libpq</> only add new
functionality, again unless mentioned in the release notes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>System Catalogs</term>
<listitem>
<para>
System catalog changes usually only affect database management tools.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Server C-language API</term>
<listitem>
<para>
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>
</varlistentry>
</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.
<productname>PostgreSQL</productname>, so no great harm can be done by
trying to start the wrong server version on a data directory.)
</para>
<para>
......@@ -1414,26 +1497,15 @@ archive_command = 'local_backup_script.sh'
pg_dumpall -p 5432 | psql -d postgres -p 6543
</programlisting>
to transfer your data. Or use an intermediate file if you wish.
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 that data. See <xref
linkend="client-authentication"> for information on how to prohibit
<application>pg_dumpall</>, otherwise you will lose those updates. 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
......@@ -1474,68 +1546,33 @@ psql -f backup postgres
moving an installation like this will not work.)
</para>
</note>
</sect2>
<sect2 id="migration-methods-other">
<title>Other data migration methods</title>
<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
testing a <productname>PostgreSQL</> major upgrade, consider the
following categories of possible changes:
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>
<variablelist>
<varlistentry>
<term>Administration</term>
<listitem>
<para>
The capabilities available for administrators to monitor and control
the server often change and improve in each major release.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SQL</term>
<listitem>
<para>
Typically this includes new SQL command capabilities and not changes
in behavior, unless specifically mentioned in the release notes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Library API</term>
<listitem>
<para>
Typically libraries like <application>libpq</> only add new
functionality, again unless mentioned in the release notes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>System Catalogs</term>
<listitem>
<para>
System catalog changes usually only affect database management tools.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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
references backend functions deep inside the server.
</para>
</listitem>
</varlistentry>
</variablelist>
<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>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment