Skip to content

P
Postgres FD Implementation
Commit c5ba11f8 authored by Bruce Momjian's avatar Bruce Momjian
Browse files
Options

Move upgrade instructions into its own section under "Server Setup and 

Operation", merged from upgrade sections in "Installation from Source
Code" and "Backup and Restore".  This now gives a single place for all
upgrade information.
parent 32866837
Expand all Show whitespace changes
Inline Side-by-side
Showing with 304 additions and 367 deletions
doc/src/sgml/backup.sgml
View file @ c5ba11f8
......@@ -1377,216 +1377,4 @@ archive_command = 'local_backup_script.sh'
</sect2>
</sect1>
<sect1 id="migration">
<title>Migration Between Releases</title>
<indexterm zone="migration">
<primary>upgrading</primary>
</indexterm>
<indexterm zone="migration">
<primary>version</primary>
<secondary>compatibility</secondary>
</indexterm>
<para>
This section discusses how to migrate your database data from one
<productname>PostgreSQL</> release to a newer one.
The software installation procedure <foreignphrase>per se</> is not the
subject of this section; those details are in <xref linkend="installation">.
</para>
<para>
<productname>PostgreSQL</> major versions are represented by the
first two digit groups of the version number, e.g., 8.4.
<productname>PostgreSQL</> minor versions are represented by the
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, 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;
minor upgrades are that simple.
</para>
<para>
For <emphasis>major</> releases of <productname>PostgreSQL</>, the
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.)
</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 &gt; 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>
doc/src/sgml/installation.sgml
View file @ c5ba11f8
......@@ -370,157 +370,6 @@ su - postgres
</sect1>
]]>
<sect1 id="install-upgrading">
<title>Upgrading</title>
<indexterm zone="install-upgrading">
<primary>upgrading</primary>
</indexterm>
<para>
These instructions assume that your existing installation is under the
<filename>/usr/local/pgsql</> directory, and that the data area is in
<filename>/usr/local/pgsql/data</>. Substitute your paths
appropriately.
</para>
<para>
The internal data storage format typically changes in every major
release of <productname>PostgreSQL</>. Therefore, if you are upgrading
an existing installation that does not have a version number of
<quote>&majorversion;.x</quote>, you must back up and restore your
data. If you are upgrading from <productname>PostgreSQL</>
<quote>&majorversion;.x</quote>, the new version can use your current
data files so you should skip the backup and restore steps below because
they are unnecessary.
</para>
<procedure>
<step>
<para>
If making a backup, make sure that your database is not being updated.
This does not affect the integrity of the backup, but the changed
data would of course not be included. If necessary, edit the
permissions in the file <filename>/usr/local/pgsql/data/pg_hba.conf</>
(or equivalent) to disallow access from everyone except you.
</para>
<para>
<indexterm>
<primary>pg_dumpall</primary>
<secondary>use during upgrade</secondary>
</indexterm>
To back up your database installation, type:
<screen>
<userinput>pg_dumpall &gt; <replaceable>outputfile</></userinput>
</screen>
If you need to preserve OIDs (such as when using them as
foreign keys), then use the <option>-o</option> option when running
<application>pg_dumpall</>.
</para>
<para>
To make the backup, you can use the <application>pg_dumpall</application>
command from the version you are currently running. For best
results, however, try to use the <application>pg_dumpall</application>
command from <productname>PostgreSQL</productname> &version;,
since this version contains bug fixes and improvements over older
versions. While this advice might seem idiosyncratic since you
haven't installed the new version yet, it is advisable to follow
it if you plan to install the new version in parallel with the
old version. In that case you can complete the installation
normally and transfer the data later. This will also decrease
the downtime.
</para>
</step>
<step>
<para>
Shut down the old server:
<screen>
<userinput>pg_ctl stop</>
</screen>
On systems that have <productname>PostgreSQL</> started at boot time,
there is probably a start-up file that will accomplish the same thing. For
example, on a <systemitem class="osname">Red Hat Linux</> system one
might find that this works:
<screen>
<userinput>/etc/rc.d/init.d/postgresql stop</userinput>
</screen>
</para>
</step>
<step>
<para>
If restoring from backup, rename or delete the old installation
directory. It is a good idea to rename the directory, rather than
delete it, in case you have trouble and need to revert to it. Keep
in mind the directory might consume significant disk space. To rename
the directory, use a command like this:
<screen>
<userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
</screen>
</para>
</step>
<step>
<para>
Install the new version of <productname>PostgreSQL</productname> as
outlined in <![%standalone-include[the next section.]]>
<![%standalone-ignore[<xref linkend="install-procedure">.]]>
</para>
</step>
<step>
<para>
Create a new database cluster if needed. Remember that you must
execute these commands while logged in to the special database user
account (which you already have if you are upgrading).
<programlisting>
<userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
</programlisting>
</para>
</step>
<step>
<para>
Restore your previous <filename>pg_hba.conf</> and any
<filename>postgresql.conf</> modifications.
</para>
</step>
<step>
<para>
Start the database server, again using the special database user
account:
<programlisting>
<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
</programlisting>
</para>
</step>
<step>
<para>
Finally, restore your data from backup with:
<screen>
<userinput>/usr/local/pgsql/bin/psql -d postgres -f <replaceable>outputfile</></userinput>
</screen>
using the <emphasis>new</> <application>psql</>.
</para>
</step>
</procedure>
<para>
Further discussion appears in
<![%standalone-include[the documentation,]]>
<![%standalone-ignore[<xref linkend="migration">,]]>
including instructions on how the previous installation can continue
running while the new installation is installed.
</para>
</sect1>
<sect1 id="install-procedure">
<title>Installation Procedure</title>
......@@ -1618,10 +1467,9 @@ PostgreSQL, contrib and HTML documentation successfully made. Ready to install.
<note>
<para>
If you are upgrading an existing system and are going to install
the new files over the old ones, be sure to back up
your data and shut down the old server before proceeding, as explained in
<xref linkend="install-upgrading"> above.
If you are upgrading an existing system be sure to read <xref
linkend="upgrading"> which has instructions about upgrading a
cluster.
</para>
</note>
......
doc/src/sgml/runtime.sgml
View file @ c5ba11f8
This diff is collapsed.
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