diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 8b79b8f82f..a461b0ac46 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1377,216 +1377,4 @@ archive_command = 'local_backup_script.sh'
-
- Migration Between Releases
-
-
- upgrading
-
-
-
- version
- compatibility
-
-
-
- This section discusses how to migrate your database data from one
- PostgreSQL release to a newer one.
- The software installation procedure per se is not the
- subject of this section; those details are in .
-
-
-
- PostgreSQL major versions are represented by the
- first two digit groups of the version number, e.g., 8.4.
- 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.
-
-
-
- For major releases of 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.
-
-
-
- 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 PostgreSQL major upgrade, consider the
- following categories of possible changes:
-
-
-
-
-
- Administration
-
-
- The capabilities available for administrators to monitor and control
- the server often change and improve in each major release.
-
-
-
-
-
- SQL
-
-
- Typically this includes new SQL command capabilities and not changes
- in behavior, unless specifically mentioned in the release notes.
-
-
-
-
-
- Library API
-
-
- Typically libraries like libpq only add new
- functionality, again unless mentioned in the release notes.
-
-
-
-
-
- System Catalogs
-
-
- System catalog changes usually only affect database management tools.
-
-
-
-
-
- Server C-language API
-
-
- 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.
-
-
-
-
-
-
-
- Migrating Data via <application>pg_dump</>
-
-
- To dump data from one major version of PostgreSQL and
- reload it in another, you must use 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
- PostgreSQL, so no great harm can be done by
- trying to start the wrong server version on a data directory.)
-
-
-
- It is recommended that you use the pg_dump and
- pg_dumpall programs from the newer version of
- 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.
-
-
-
- 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:
-
-
-pg_dumpall -p 5432 | psql -d postgres -p 6543
-
-
- 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
- pg_dumpall, otherwise you will lose those updates. See
- for information on how to prohibit
- access.
-
-
-
- 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:
-
-
-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
-
-
- See about ways to start and stop the
- server and other details. The installation instructions will advise
- you of strategic places to perform these steps.
-
-
-
-
- When you move the old installation out of the way
- 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 PostgreSQL version 8.0 and later, so long
- as you move all subdirectories containing installed files together;
- for example if /usr/local/postgres/bin/ goes to
- /usr/local/postgres.old/bin/, then
- /usr/local/postgres/share/ must go to
- /usr/local/postgres.old/share/. In pre-8.0 releases
- moving an installation like this will not work.)
-
-
-
-
-
- Other Data Migration Methods
-
-
- The contrib program
- pg_upgrade
- allows an installation to be migrated in-place from one major
- PostgreSQL version to the next. Keep in mind that this
- method does not provide any scope for running old and new versions
- concurrently. Also, pg_upgrade is much less
- battle-tested than pg_dump, so having an
- up-to-date backup is strongly recommended in case something goes wrong.
-
-
-
- It is also possible to use certain replication methods, such as
- Slony, to create a standby server with the updated version of
- 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 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.
-
-
-
-
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index b86581f2ab..0258eecda4 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -370,157 +370,6 @@ su - postgres
]]>
-
- Upgrading
-
-
- upgrading
-
-
-
- These instructions assume that your existing installation is under the
- /usr/local/pgsql directory, and that the data area is in
- /usr/local/pgsql/data. Substitute your paths
- appropriately.
-
-
-
- The internal data storage format typically changes in every major
- release of PostgreSQL. Therefore, if you are upgrading
- an existing installation that does not have a version number of
- &majorversion;.x, you must back up and restore your
- data. If you are upgrading from PostgreSQL
- &majorversion;.x, the new version can use your current
- data files so you should skip the backup and restore steps below because
- they are unnecessary.
-
-
-
-
-
- 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 /usr/local/pgsql/data/pg_hba.conf
- (or equivalent) to disallow access from everyone except you.
-
-
-
-
- pg_dumpall
- use during upgrade
-
-
- To back up your database installation, type:
-
-pg_dumpall > outputfile
-
- If you need to preserve OIDs (such as when using them as
- foreign keys), then use the option when running
- pg_dumpall.
-
-
-
- To make the backup, you can use the pg_dumpall
- command from the version you are currently running. For best
- results, however, try to use the pg_dumpall
- command from PostgreSQL &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.
-
-
-
-
-
- Shut down the old server:
-
-pg_ctl stop
-
- On systems that have PostgreSQL started at boot time,
- there is probably a start-up file that will accomplish the same thing. For
- example, on a Red Hat Linux system one
- might find that this works:
-
-/etc/rc.d/init.d/postgresql stop
-
-
-
-
-
-
- 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:
-
-mv /usr/local/pgsql /usr/local/pgsql.old
-
-
-
-
-
-
- Install the new version of PostgreSQL as
- outlined in
- .]]>
-
-
-
-
-
- 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).
-
-/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
-
-
-
-
-
-
- Restore your previous pg_hba.conf and any
- postgresql.conf modifications.
-
-
-
-
-
- Start the database server, again using the special database user
- account:
-
-/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
-
-
-
-
-
-
- Finally, restore your data from backup with:
-
-/usr/local/pgsql/bin/psql -d postgres -f outputfile
-
- using the new psql.
-
-
-
-
-
- Further discussion appears in
-
- ,]]>
- including instructions on how the previous installation can continue
- running while the new installation is installed.
-
-
-
-
Installation Procedure
@@ -1618,10 +1467,9 @@ PostgreSQL, contrib and HTML documentation successfully made. Ready to install.
- 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
- above.
+ If you are upgrading an existing system be sure to read which has instructions about upgrading a
+ cluster.
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index be409c20d4..42a2950aa6 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1418,6 +1418,307 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
+
+ Upgrading a <productname>PostgreSQL</> Cluster
+
+
+ upgrading
+
+
+
+ version
+ compatibility
+
+
+
+ This section discusses how to upgrade your database data from one
+ PostgreSQL release to a newer one.
+
+
+
+ PostgreSQL major versions are represented by the
+ first two digit groups of the version number, e.g., 8.4.
+ 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.
+
+
+
+ For major releases of 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.
+
+
+
+ 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 (); 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.
+
+
+
+ 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 PostgreSQL major upgrade, consider the
+ following categories of possible changes:
+
+
+
+
+
+ Administration
+
+
+ The capabilities available for administrators to monitor and control
+ the server often change and improve in each major release.
+
+
+
+
+
+ SQL
+
+
+ Typically this includes new SQL command capabilities and not changes
+ in behavior, unless specifically mentioned in the release notes.
+
+
+
+
+
+ Library API
+
+
+ Typically libraries like libpq only add new
+ functionality, again unless mentioned in the release notes.
+
+
+
+
+
+ System Catalogs
+
+
+ System catalog changes usually only affect database management tools.
+
+
+
+
+
+ Server C-language API
+
+
+ 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.
+
+
+
+
+
+
+
+ Upgrading Data via <application>pg_dump</>
+
+
+ To dump data from one major version of PostgreSQL and
+ reload it in another, you must use 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
+ PostgreSQL, so no great harm can be done by
+ trying to start the wrong server version on a data directory.)
+
+
+
+ It is recommended that you use the pg_dump and
+ pg_dumpall programs from the newer version of
+ 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.
+
+
+
+ These instructions assume that your existing installation is under the
+ /usr/local/pgsql directory, and that the data area is in
+ /usr/local/pgsql/data. Substitute your paths
+ appropriately.
+
+
+
+
+
+ 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 /usr/local/pgsql/data/pg_hba.conf
+ (or equivalent) to disallow access from everyone except you.
+ See for additional information on
+ access control.
+
+
+
+
+ pg_dumpall
+ use during upgrade
+
+
+ To back up your database installation, type:
+
+pg_dumpall > outputfile
+
+ If you need to preserve OIDs (such as when using them as
+ foreign keys), then use the option when running
+ pg_dumpall.
+
+
+
+ To make the backup, you can use the pg_dumpall
+ command from the version you are currently running. For best
+ results, however, try to use the pg_dumpall
+ command from PostgreSQL &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.
+
+
+
+
+
+ Shut down the old server:
+
+pg_ctl stop
+
+ On systems that have PostgreSQL started at boot time,
+ there is probably a start-up file that will accomplish the same thing. For
+ example, on a Red Hat Linux system one
+ might find that this works:
+
+/etc/rc.d/init.d/postgresql stop
+
+
+ See for details about starting and
+ stoping the server.
+
+
+
+
+ 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:
+
+mv /usr/local/pgsql /usr/local/pgsql.old
+
+ (Be sure to move the directory as a single unit so relative paths
+ remain unchanged.)
+
+
+
+
+
+ Install the new version of PostgreSQL as
+ outlined in
+ .]]>
+
+
+
+
+
+ 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).
+
+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+
+
+
+
+
+
+ Restore your previous pg_hba.conf and any
+ postgresql.conf modifications.
+
+
+
+
+
+ Start the database server, again using the special database user
+ account:
+
+/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
+
+
+
+
+
+
+ Finally, restore your data from backup with:
+
+/usr/local/pgsql/bin/psql -d postgres -f outputfile
+
+ using the new psql.
+
+
+
+
+
+ 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:
+
+
+pg_dumpall -p 5432 | psql -d postgres -p 5433
+
+ to transfer your data.
+
+
+
+
+
+ Other data migration methods
+
+
+ The contrib program
+ pg_upgrade
+ allows an installation to be migrated in-place from one major
+ PostgreSQL version to the next. Keep in mind that this
+ method does not provide any scope for running old and new versions
+ concurrently. Also, pg_upgrade is much less
+ battle-tested than pg_dump, so having an
+ up-to-date backup is strongly recommended in case something goes wrong.
+
+
+
+ It is also possible to use certain replication methods, such as
+ Slony, to create a standby server with the updated version of
+ 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 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.
+
+
+
+
+
Preventing Server Spoofing