From c5ba11f8fb1701441b96a755ea410b96bfe36170 Mon Sep 17 00:00:00 2001 From: Bruce Momjian 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 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 -- 2.40.0