From f0f46ed66a177e5349a6d84e8fff91e6aa6b0dac Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 15 Aug 2010 23:04:49 +0000 Subject: [PATCH] Assorted improvements to backup/restore documentation, per Thom Brown. --- doc/src/sgml/backup.sgml | 231 +++++++++++++++++++++++---------------- 1 file changed, 134 insertions(+), 97 deletions(-) diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index 2f271efc4c..b5fe2f84f1 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -1,4 +1,4 @@ - + Backup and Restore @@ -20,7 +20,8 @@ File system level backup Continuous archiving - 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. @@ -73,6 +74,16 @@ pg_dump dbname > ). + + An important advantage of pg_dump over the other backup + methods described later is that pg_dump's output can + generally be re-loaded into newer versions of PostgreSQL, + whereas file-level backups and continuous archiving are both extremely + server-version-specific. 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. + + Dumps created by 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 pg_dumpall do not produce file-system-level backups and cannot be used as part of a continuous-archiving solution. Such dumps are logical and do not contain enough - information to used by WAL reply. + information to be used by WAL replay. @@ -1373,12 +1384,12 @@ archive_command = 'local_backup_script.sh' 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. 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 — @@ -1387,98 +1398,18 @@ archive_command = 'local_backup_script.sh' For major releases of PostgreSQL, the - internal data storage format is subject to change. When migrating - data from one major version of PostgreSQL to another, - you need to back up your data and restore it on the new server. - This must be done using 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. + 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. - 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 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 that data. See for information on how to prohibit - access. - - - - It is also possible to use 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. - - - - 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.) - - - - - 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 + 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: @@ -1528,8 +1459,8 @@ psql -f backup postgres Server C-language API - This involved changes in the backend function API, which is written - in the C programming language. Such changes effect code that + 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. @@ -1537,5 +1468,111 @@ psql -f backup postgres + + 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. + + +