begriffs open source - ai-pg/blob - full-docs/txt/upgrading.txt

   1
   2 18.6. Upgrading a PostgreSQL Cluster #
   3
   4    18.6.1. Upgrading Data via pg_dumpall
   5    18.6.2. Upgrading Data via pg_upgrade
   6    18.6.3. Upgrading Data via Replication
   7
   8    This section discusses how to upgrade your database data from one
   9    PostgreSQL release to a newer one.
  10
  11    Current PostgreSQL version numbers consist of a major and a minor
  12    version number. For example, in the version number 10.1, the 10 is the
  13    major version number and the 1 is the minor version number, meaning
  14    this would be the first minor release of the major release 10. For
  15    releases before PostgreSQL version 10.0, version numbers consist of
  16    three numbers, for example, 9.5.3. In those cases, the major version
  17    consists of the first two digit groups of the version number, e.g.,
  18    9.5, and the minor version is the third number, e.g., 3, meaning this
  19    would be the third minor release of the major release 9.5.
  20
  21    Minor releases never change the internal storage format and are always
  22    compatible with earlier and later minor releases of the same major
  23    version number. For example, version 10.1 is compatible with version
  24    10.0 and version 10.6. Similarly, for example, 9.5.3 is compatible with
  25    9.5.0, 9.5.1, and 9.5.6. To update between compatible versions, you
  26    simply replace the executables while the server is down and restart the
  27    server. The data directory remains unchanged — minor upgrades are that
  28    simple.
  29
  30    For major releases of PostgreSQL, the internal data storage format is
  31    subject to change, thus complicating upgrades. The traditional method
  32    for moving data to a new major version is to dump and restore the
  33    database, though this can be slow. A faster method is pg_upgrade.
  34    Replication methods are also available, as discussed below. (If you are
  35    using a pre-packaged version of PostgreSQL, it may provide scripts to
  36    assist with major version upgrades. Consult the package-level
  37    documentation for details.)
  38
  39    New major versions also typically introduce some user-visible
  40    incompatibilities, so application programming changes might be
  41    required. All user-visible changes are listed in the release notes
  42    (Appendix E); pay particular attention to the section labeled
  43    "Migration". Though you can upgrade from one major version to another
  44    without upgrading to intervening versions, you should read the major
  45    release notes of all intervening versions.
  46
  47    Cautious users will want to test their client applications on the new
  48    version before switching over fully; therefore, it's often a good idea
  49    to set up concurrent installations of old and new versions. When
  50    testing a PostgreSQL major upgrade, consider the following categories
  51    of possible changes:
  52
  53    Administration
  54           The capabilities available for administrators to monitor and
  55           control the server often change and improve in each major
  56           release.
  57
  58    SQL
  59           Typically this includes new SQL command capabilities and not
  60           changes in behavior, unless specifically mentioned in the
  61           release notes.
  62
  63    Library API
  64           Typically libraries like libpq only add new functionality, again
  65           unless mentioned in the release notes.
  66
  67    System Catalogs
  68           System catalog changes usually only affect database management
  69           tools.
  70
  71    Server C-language API
  72           This involves changes in the backend function API, which is
  73           written in the C programming language. Such changes affect code
  74           that references backend functions deep inside the server.
  75
  76 18.6.1. Upgrading Data via pg_dumpall #
  77
  78    One upgrade method is to dump data from one major version of PostgreSQL
  79    and restore it in another — to do this, you must use a logical backup
  80    tool like pg_dumpall; file system level backup methods will not work.
  81    (There are checks in place that prevent you from using a data directory
  82    with an incompatible version of PostgreSQL, so no great harm can be
  83    done by trying to start the wrong server version on a data directory.)
  84
  85    It is recommended that you use the pg_dump and pg_dumpall programs from
  86    the newer version of PostgreSQL, to take advantage of enhancements that
  87    might have been made in these programs. Current releases of the dump
  88    programs can read data from any server version back to 9.2.
  89
  90    These instructions assume that your existing installation is under the
  91    /usr/local/pgsql directory, and that the data area is in
  92    /usr/local/pgsql/data. Substitute your paths appropriately.
  93     1. If making a backup, make sure that your database is not being
  94        updated. This does not affect the integrity of the backup, but the
  95        changed data would of course not be included. If necessary, edit
  96        the permissions in the file /usr/local/pgsql/data/pg_hba.conf (or
  97        equivalent) to disallow access from everyone except you. See
  98        Chapter 20 for additional information on access control.
  99        To back up your database installation, type:
 100 pg_dumpall > outputfile
 101
 102        To make the backup, you can use the pg_dumpall command from the
 103        version you are currently running; see Section 25.1.2 for more
 104        details. For best results, however, try to use the pg_dumpall
 105        command from PostgreSQL 18.0, since this version contains bug fixes
 106        and improvements over older versions. While this advice might seem
 107        idiosyncratic since you haven't installed the new version yet, it
 108        is advisable to follow it if you plan to install the new version in
 109        parallel with the old version. In that case you can complete the
 110        installation normally and transfer the data later. This will also
 111        decrease the downtime.
 112     2. Shut down the old server:
 113 pg_ctl stop
 114
 115        On systems that have PostgreSQL started at boot time, there is
 116        probably a start-up file that will accomplish the same thing. For
 117        example, on a Red Hat Linux system one might find that this works:
 118 /etc/rc.d/init.d/postgresql stop
 119
 120        See Chapter 18 for details about starting and stopping the server.
 121     3. If restoring from backup, rename or delete the old installation
 122        directory if it is not version-specific. It is a good idea to
 123        rename the directory, rather than delete it, in case you have
 124        trouble and need to revert to it. Keep in mind the directory might
 125        consume significant disk space. To rename the directory, use a
 126        command like this:
 127 mv /usr/local/pgsql /usr/local/pgsql.old
 128
 129        (Be sure to move the directory as a single unit so relative paths
 130        remain unchanged.)
 131     4. Install the new version of PostgreSQL as outlined in Chapter 17.
 132     5. Create a new database cluster if needed. Remember that you must
 133        execute these commands while logged in to the special database user
 134        account (which you already have if you are upgrading).
 135 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
 136
 137     6. Restore your previous pg_hba.conf and any postgresql.conf
 138        modifications.
 139     7. Start the database server, again using the special database user
 140        account:
 141 /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
 142
 143     8. Finally, restore your data from backup with:
 144 /usr/local/pgsql/bin/psql -d postgres -f outputfile
 145
 146        using the new psql.
 147
 148    The least downtime can be achieved by installing the new server in a
 149    different directory and running both the old and the new servers in
 150    parallel, on different ports. Then you can use something like:
 151 pg_dumpall -p 5432 | psql -d postgres -p 5433
 152
 153    to transfer your data.
 154
 155 18.6.2. Upgrading Data via pg_upgrade #
 156
 157    The pg_upgrade module allows an installation to be migrated in-place
 158    from one major PostgreSQL version to another. Upgrades can be performed
 159    in minutes, particularly with --link mode. It requires steps similar to
 160    pg_dumpall above, e.g., starting/stopping the server, running initdb.
 161    The pg_upgrade documentation outlines the necessary steps.
 162
 163 18.6.3. Upgrading Data via Replication #
 164
 165    It is also possible to use logical replication methods to create a
 166    standby server with the updated version of PostgreSQL. This is possible
 167    because logical replication supports replication between different
 168    major versions of PostgreSQL. The standby can be on the same computer
 169    or a different computer. Once it has synced up with the primary server
 170    (running the older version of PostgreSQL), you can switch primaries and
 171    make the standby the primary and shut down the older database instance.
 172    Such a switch-over results in only several seconds of downtime for an
 173    upgrade.
 174
 175    This method of upgrading can be performed using the built-in logical
 176    replication facilities as well as using external logical replication
 177    systems such as pglogical, Slony, Londiste, and Bucardo.