begriffs open source - ai-pg/blob - full-docs/src/sgml/html/upgrading.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>18.6. Upgrading a PostgreSQL Cluster</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="server-shutdown.html" title="18.5. Shutting Down the Server" /><link rel="next" href="preventing-server-spoofing.html" title="18.7. Preventing Server Spoofing" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">18.6. Upgrading a <span class="productname">PostgreSQL</span> Cluster</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="server-shutdown.html" title="18.5. Shutting Down the Server">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime.html" title="Chapter 18. Server Setup and Operation">Up</a></td><th width="60%" align="center">Chapter 18. Server Setup and Operation</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="preventing-server-spoofing.html" title="18.7. Preventing Server Spoofing">Next</a></td></tr></table><hr /></div><div class="sect1" id="UPGRADING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">18.6. Upgrading a <span class="productname">PostgreSQL</span> Cluster <a href="#UPGRADING" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="upgrading.html#UPGRADING-VIA-PGDUMPALL">18.6.1. Upgrading Data via <span class="application">pg_dumpall</span></a></span></dt><dt><span class="sect2"><a href="upgrading.html#UPGRADING-VIA-PG-UPGRADE">18.6.2. Upgrading Data via <span class="application">pg_upgrade</span></a></span></dt><dt><span class="sect2"><a href="upgrading.html#UPGRADING-VIA-REPLICATION">18.6.3. Upgrading Data via Replication</a></span></dt></dl></div><a id="id-1.6.5.9.2" class="indexterm"></a><a id="id-1.6.5.9.3" class="indexterm"></a><p>
   3    This section discusses how to upgrade your database data from one
   4    <span class="productname">PostgreSQL</span> release to a newer one.
   5   </p><p>
   6    Current <span class="productname">PostgreSQL</span> version numbers consist of a
   7    major and a minor version number.  For example, in the version number 10.1,
   8    the 10 is the major version number and the 1 is the minor version number,
   9    meaning this would be the first minor release of the major release 10.  For
  10    releases before <span class="productname">PostgreSQL</span> version 10.0, version
  11    numbers consist of three numbers, for example, 9.5.3.  In those cases, the
  12    major version consists of the first two digit groups of the version number,
  13    e.g., 9.5, and the minor version is the third number, e.g., 3, meaning this
  14    would be the third minor release of the major release 9.5.
  15   </p><p>
  16    Minor releases never change the internal storage format and are always
  17    compatible with earlier and later minor releases of the same major version
  18    number.  For example, version 10.1 is compatible with version 10.0 and
  19    version 10.6.  Similarly, for example, 9.5.3 is compatible with 9.5.0,
  20    9.5.1, and 9.5.6.  To update between compatible versions, you simply
  21    replace the executables while the server is down and restart the server.
  22    The data directory remains unchanged — minor upgrades are that
  23    simple.
  24   </p><p>
  25    For <span class="emphasis"><em>major</em></span> releases of <span class="productname">PostgreSQL</span>, the
  26    internal data storage format is subject to change, thus complicating
  27    upgrades.  The traditional method for moving data to a new major version
  28    is to dump and restore the database, though this can be slow.  A
  29    faster method is <a class="xref" href="pgupgrade.html" title="pg_upgrade"><span class="refentrytitle"><span class="application">pg_upgrade</span></span></a>.  Replication methods are
  30    also available, as discussed below.
  31    (If you are using a pre-packaged version
  32    of <span class="productname">PostgreSQL</span>, it may provide scripts to
  33    assist with major version upgrades.  Consult the package-level
  34    documentation for details.)
  35   </p><p>
  36    New major versions also typically introduce some user-visible
  37    incompatibilities, so application programming changes might be required.
  38    All user-visible changes are listed in the release notes (<a class="xref" href="release.html" title="Appendix E. Release Notes">Appendix E</a>);  pay particular attention to the section
  39    labeled "Migration".  Though you can upgrade from one major version
  40    to another without upgrading to intervening versions, you should read
  41    the major release notes of all intervening versions.
  42   </p><p>
  43    Cautious users will want to test their client applications on the new
  44    version before switching over fully; therefore, it's often a good idea to
  45    set up concurrent installations of old and new versions.  When
  46    testing a <span class="productname">PostgreSQL</span> major upgrade, consider the
  47    following categories of possible changes:
  48   </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Administration</span></dt><dd><p>
  49       The capabilities available for administrators to monitor and control
  50       the server often change and improve in each major release.
  51      </p></dd><dt><span class="term">SQL</span></dt><dd><p>
  52       Typically this includes new SQL command capabilities and not changes
  53       in behavior, unless specifically mentioned in the release notes.
  54      </p></dd><dt><span class="term">Library API</span></dt><dd><p>
  55       Typically libraries like <span class="application">libpq</span> only add new
  56       functionality, again unless mentioned in the release notes.
  57      </p></dd><dt><span class="term">System Catalogs</span></dt><dd><p>
  58       System catalog changes usually only affect database management tools.
  59      </p></dd><dt><span class="term">Server C-language API</span></dt><dd><p>
  60       This involves changes in the backend function API, which is written
  61       in the C programming language.  Such changes affect code that
  62       references backend functions deep inside the server.
  63      </p></dd></dl></div><div class="sect2" id="UPGRADING-VIA-PGDUMPALL"><div class="titlepage"><div><div><h3 class="title">18.6.1. Upgrading Data via <span class="application">pg_dumpall</span> <a href="#UPGRADING-VIA-PGDUMPALL" class="id_link">#</a></h3></div></div></div><p>
  64     One upgrade method is to dump data from one major version of
  65     <span class="productname">PostgreSQL</span> and restore it in another —  to do
  66     this, you must use a <span class="emphasis"><em>logical</em></span> backup tool like
  67     <span class="application">pg_dumpall</span>; file system
  68     level backup methods will not work. (There are checks in place that prevent
  69     you from using a data directory with an incompatible version of
  70     <span class="productname">PostgreSQL</span>, so no great harm can be done by
  71     trying to start the wrong server version on a data directory.)
  72    </p><p>
  73     It is recommended that you use the <span class="application">pg_dump</span> and
  74     <span class="application">pg_dumpall</span> programs from the <span class="emphasis"><em>newer</em></span>
  75     version of
  76     <span class="productname">PostgreSQL</span>, to take advantage of enhancements
  77     that might have been made in these programs.  Current releases of the
  78     dump programs can read data from any server version back to 9.2.
  79    </p><p>
  80     These instructions assume that your existing installation is under the
  81     <code class="filename">/usr/local/pgsql</code> directory, and that the data area is in
  82     <code class="filename">/usr/local/pgsql/data</code>.  Substitute your paths
  83     appropriately.
  84    </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
  85       If making a backup, make sure that your database is not being updated.
  86       This does not affect the integrity of the backup, but the changed
  87       data would of course not be included. If necessary, edit the
  88       permissions in the file <code class="filename">/usr/local/pgsql/data/pg_hba.conf</code>
  89       (or equivalent) to disallow access from everyone except you.
  90       See <a class="xref" href="client-authentication.html" title="Chapter 20. Client Authentication">Chapter 20</a> for additional information on
  91       access control.
  92      </p><p>
  93       <a id="id-1.6.5.9.11.5.1.2.1" class="indexterm"></a>
  94
  95       To back up your database installation, type:
  96 </p><pre class="screen">
  97 <strong class="userinput"><code>pg_dumpall &gt; <em class="replaceable"><code>outputfile</code></em></code></strong>
  98 </pre><p>
  99      </p><p>
 100       To make the backup, you can use the <span class="application">pg_dumpall</span>
 101       command from the version you are currently running;  see <a class="xref" href="backup-dump.html#BACKUP-DUMP-ALL" title="25.1.2. Using pg_dumpall">Section 25.1.2</a> for more details.  For best
 102       results, however, try to use the <span class="application">pg_dumpall</span>
 103       command from <span class="productname">PostgreSQL</span> 18.0,
 104       since this version contains bug fixes and improvements over older
 105       versions.  While this advice might seem idiosyncratic since you
 106       haven't installed the new version yet, it is advisable to follow
 107       it if you plan to install the new version in parallel with the
 108       old version.  In that case you can complete the installation
 109       normally and transfer the data later.  This will also decrease
 110       the downtime.
 111      </p></li><li class="step"><p>
 112       Shut down the old server:
 113 </p><pre class="screen">
 114 <strong class="userinput"><code>pg_ctl stop</code></strong>
 115 </pre><p>
 116       On systems that have <span class="productname">PostgreSQL</span> started at boot time,
 117       there is probably a start-up file that will accomplish the same thing. For
 118       example, on a <span class="systemitem">Red Hat Linux</span> system one
 119       might find that this works:
 120 </p><pre class="screen">
 121 <strong class="userinput"><code>/etc/rc.d/init.d/postgresql stop</code></strong>
 122 </pre><p>
 123       See <a class="xref" href="runtime.html" title="Chapter 18. Server Setup and Operation">Chapter 18</a> for details about starting and
 124       stopping the server.
 125      </p></li><li class="step"><p>
 126       If restoring from backup, rename or delete the old installation
 127       directory if it is not version-specific.  It is a good idea to
 128       rename the directory, rather than
 129       delete it, in case you have trouble and need to revert to it.  Keep
 130       in mind the directory might consume significant disk space.  To rename
 131       the directory, use a command like this:
 132 </p><pre class="screen">
 133 <strong class="userinput"><code>mv /usr/local/pgsql /usr/local/pgsql.old</code></strong>
 134 </pre><p>
 135      (Be sure to move the directory as a single unit so relative paths
 136      remain unchanged.)
 137      </p></li><li class="step"><p>
 138       Install the new version of <span class="productname">PostgreSQL</span> as
 139       outlined in <a class="xref" href="installation.html" title="Chapter 17. Installation from Source Code">Chapter 17</a>.
 140      </p></li><li class="step"><p>
 141       Create a new database cluster if needed.  Remember that you must
 142       execute these commands while logged in to the special database user
 143       account (which you already have if you are upgrading).
 144 </p><pre class="programlisting">
 145 <strong class="userinput"><code>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</code></strong>
 146 </pre><p>
 147      </p></li><li class="step"><p>
 148       Restore your previous <code class="filename">pg_hba.conf</code> and any
 149       <code class="filename">postgresql.conf</code> modifications.
 150      </p></li><li class="step"><p>
 151       Start the database server, again using the special database user
 152       account:
 153 </p><pre class="programlisting">
 154 <strong class="userinput"><code>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</code></strong>
 155 </pre><p>
 156      </p></li><li class="step"><p>
 157       Finally, restore your data from backup with:
 158 </p><pre class="screen">
 159 <strong class="userinput"><code>/usr/local/pgsql/bin/psql -d postgres -f <em class="replaceable"><code>outputfile</code></em></code></strong>
 160 </pre><p>
 161       using the <span class="emphasis"><em>new</em></span> <span class="application">psql</span>.
 162      </p></li></ol></div><p>
 163     The least downtime can be achieved by installing the new server in
 164     a different directory and running both the old and the new servers
 165     in parallel, on different ports. Then you can use something like:
 166
 167 </p><pre class="programlisting">
 168 pg_dumpall -p 5432 | psql -d postgres -p 5433
 169 </pre><p>
 170     to transfer your data.
 171    </p></div><div class="sect2" id="UPGRADING-VIA-PG-UPGRADE"><div class="titlepage"><div><div><h3 class="title">18.6.2. Upgrading Data via <span class="application">pg_upgrade</span> <a href="#UPGRADING-VIA-PG-UPGRADE" class="id_link">#</a></h3></div></div></div><p>
 172     The <a class="xref" href="pgupgrade.html" title="pg_upgrade"><span class="refentrytitle"><span class="application">pg_upgrade</span></span></a> module allows an installation to
 173     be migrated in-place from one major <span class="productname">PostgreSQL</span>
 174     version to another.  Upgrades can be performed in minutes,
 175     particularly with <code class="option">--link</code> mode.  It requires steps similar to
 176     <span class="application">pg_dumpall</span> above, e.g.,  starting/stopping the server,
 177     running <span class="application">initdb</span>.  The <span class="application">pg_upgrade</span> <a class="link" href="pgupgrade.html" title="pg_upgrade">documentation</a> outlines the necessary steps.
 178    </p></div><div class="sect2" id="UPGRADING-VIA-REPLICATION"><div class="titlepage"><div><div><h3 class="title">18.6.3. Upgrading Data via Replication <a href="#UPGRADING-VIA-REPLICATION" class="id_link">#</a></h3></div></div></div><p>
 179     It is also possible to use logical replication methods to create a standby
 180     server with the updated version of <span class="productname">PostgreSQL</span>.
 181     This is possible because logical replication supports
 182     replication between different major versions of
 183     <span class="productname">PostgreSQL</span>.  The standby can be on the same computer or
 184     a different computer.  Once it has synced up with the primary server
 185     (running the older version of <span class="productname">PostgreSQL</span>), you can
 186     switch primaries and make the standby the primary and shut down the older
 187     database instance.  Such a switch-over results in only several seconds
 188     of downtime for an upgrade.
 189    </p><p>
 190     This method of upgrading can be performed using the built-in logical
 191     replication facilities as well as using external logical replication
 192     systems such as <span class="productname">pglogical</span>,
 193     <span class="productname">Slony</span>, <span class="productname">Londiste</span>, and
 194     <span class="productname">Bucardo</span>.
 195    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="server-shutdown.html" title="18.5. Shutting Down the Server">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime.html" title="Chapter 18. Server Setup and Operation">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="preventing-server-spoofing.html" title="18.7. Preventing Server Spoofing">Next</a></td></tr><tr><td width="40%" align="left" valign="top">18.5. Shutting Down the Server </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 18.7. Preventing Server Spoofing</td></tr></table></div></body></html>