From: Tom Lane Date: Sun, 15 Aug 2010 23:04:49 +0000 (+0000) Subject: Assorted improvements to backup/restore documentation, per Thom Brown. X-Git-Tag: REL9_1_ALPHA1~75 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f0f46ed66a177e5349a6d84e8fff91e6aa6b0dac;p=postgresql Assorted improvements to backup/restore documentation, per Thom Brown. --- 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,14 +1398,86 @@ 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 + 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. + PostgreSQL, so no great harm can be done by + trying to start the wrong server version on a data directory.) @@ -1414,26 +1497,15 @@ archive_command = 'local_backup_script.sh' pg_dumpall -p 5432 | psql -d postgres -p 6543 - to transfer your data. Or use an intermediate file if you wish. + 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 that data. See for information on how to prohibit + pg_dumpall, otherwise you will lose those updates. 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 @@ -1474,68 +1546,33 @@ psql -f backup postgres moving an installation like this will not work.) + + + + Other data migration methods - 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 - testing a PostgreSQL major upgrade, consider the - following categories of possible changes: + 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. - - - - 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 involved changes in the backend function API, which is written - in the C programming language. Such changes effect code that - references backend functions deep inside the server. - - - - - + + 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. + +