-
-
Migration Between Releases
-
-
-
-
-
- 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
- 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.
-
-
-
-
]]>
-
-
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.
-
-
-
- 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 -o option when running
-
-
- 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
-
-
-
-
-
- Further discussion appears in
-
- ,]]>
- including instructions on how the previous installation can continue
- running while the new installation is installed.
-
-
-
-
Installation Procedure
- 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
+ linkend="upgrading"> which has instructions about upgrading a
+ cluster.
+
+
Upgrading a <productname>PostgreSQL</> Cluster
+
+
+
+
+
+ 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 (
+ 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.
+
+
+ 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.
+
+
+
+ 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 -o option when running
+
+
+ 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
+
+
+
+
+
+ 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
+ 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
projects / postgresql.git / commitdiff