From c5ba11f8fb1701441b96a755ea410b96bfe36170 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Mon, 31 Jan 2011 12:32:03 -0500
Subject: [PATCH] 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.
---
doc/src/sgml/backup.sgml | 212 -----------------------
doc/src/sgml/installation.sgml | 158 +----------------
doc/src/sgml/runtime.sgml | 301 +++++++++++++++++++++++++++++++++
3 files changed, 304 insertions(+), 367 deletions(-)
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 8b79b8f82f7..a461b0ac46a 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -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 —
- 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 > 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>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index b86581f2abb..0258eecda43 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -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 > <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>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index be409c20d46..42a2950aa61 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1418,6 +1418,307 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
</para>
</sect1>
+ <sect1 id="upgrading">
+ <title>Upgrading a <productname>PostgreSQL</> Cluster</title>
+
+ <indexterm zone="upgrading">
+ <primary>upgrading</primary>
+ </indexterm>
+
+ <indexterm zone="upgrading">
+ <primary>version</primary>
+ <secondary>compatibility</secondary>
+ </indexterm>
+
+ <para>
+ This section discusses how to upgrade your database data from one
+ <productname>PostgreSQL</> release to a newer one.
+ </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 —
+ 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 methods are available,
+ as discussed below.
+ </para>
+
+ <para>
+ New major versions also typically introduce some user-visible
+ incompatibilities, so application programming changes might be required.
+ All user-visible changes are listed in the release notes (<xref
+ linkend="release">); pay particular attention to the section
+ labeled "Migration". If you are upgrading across several major
+ versions, be sure to read the release notes for each intervening
+ version.
+ </para>
+
+ <para>
+ 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="upgrade-methods-pgdump">
+ <title>Upgrading 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>
+ 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>
+
+ <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.
+ See <xref linkend="client-authentication"> for additional information on
+ access control.
+ </para>
+
+ <para>
+ <indexterm>
+ <primary>pg_dumpall</primary>
+ <secondary>use during upgrade</secondary>
+ </indexterm>
+
+ To back up your database installation, type:
+<screen>
+<userinput>pg_dumpall > <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>
+ See <xref linkend="runtime"> for details about starting and
+ stoping the server.
+ </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>
+ (Be sure to move the directory as a single unit so relative paths
+ remain unchanged.)
+ </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>
+ 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 5433
+</programlisting>
+ to transfer your data.
+ </para>
+
+ </sect2>
+
+ <sect2 id="upgrading-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>
+
<sect1 id="preventing-server-spoofing">
<title>Preventing Server Spoofing</title>
--
GitLab