<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_upgrade.sgml,v 1.20 2002/01/13 01:13:59 momjian Exp $
PostgreSQL documentation
-->

<refentry id="APP-PG-UPGRADE">
 <refmeta>
  <refentrytitle id="APP-PG-UPGRADE-TITLE">
   <application>pg_upgrade</application>
  </refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   <application>pg_upgrade</application>
  </refname>
  <refpurpose>
   Allows upgrade from a previous release without reloading data
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-31</date>
  </refsynopsisdivinfo>
  <cmdsynopsis>
   <command>pg_upgrade</command>
    <group choice="plain"><arg>-1</arg><arg>-2</arg></group>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="R1-APP-PG-UPGRADE-1">
  <refsect1info>
   <date>1999-07-31</date>
  </refsect1info>
  <title>
   Description
  </title>

  <para>
   <application>pg_upgrade</application>
   is a utility for upgrading from a previous
   <productname>PostgreSQL</productname> release without reloading all the data.
   Not all <productname>PostgreSQL</productname> release transitions can be
   handled this way.  Check the release notes for details on your installation.
  </para>

  <procedure>
   <title>Upgrading <productname>PostgreSQL</productname> with pg_upgrade</title>

   <step performance="required">
    <para>
     Back up your existing data directory, preferably by making a
     complete dump with pg_dumpall.
    </para>
   </step>

   <step performance="required">
    <para>
     Copy the program <filename>pgsql/src/bin/pg_dump/pg_upgrade</filename>
     from the current PostgreSQL distribution into somewhere in your path.
    </para>
   </step>

   <step performance="required">
    <para>
     Change your working directory to the 
     pgsql main directory, and type:
     <programlisting>
$ pg_upgrade -1
     </programlisting>
     to collect information about the old database needed for the
     upgrade.
    </para>
   </step>

   <step performance="required">
    <para>
     Do:
     <programlisting>
$ make install
     </programlisting>
     to install the new binaries.
    </para>
   </step>

   <step performance="required">
    <para>
     Do:
     <programlisting>
$ cd pgsql/contrib/pg_resetxlog
$ make install
     </programlisting>
     to install the /contrib/pg_resetxlog utility 
     which will be used by pg_upgrade.
    </para>
   </step>

   <step performance="required">
    <para>
     Run <application>initdb</application> to create a new template1 database
     containing the system tables for the new release.  Make sure you use
     settings similar to those used in your previous version.
    </para>
   </step>

   <step performance="required">
    <para>
     Start the new postmaster.  (Note: it is critical that no users connect
     to the server until the upgrade is complete.  You may wish to start
     the postmaster without -i and/or alter <filename>pg_hba.conf</filename>
     temporarily.)
    </para>
   </step>

   <step performance="required">
    <para>
     Change your working directory to the 
     pgsql main directory, and type:
     <programlisting>
$ pg_upgrade -2
     </programlisting>
     The program will do some checking to make sure everything is properly
     configured, and will run your db.out script to recreate all the databases
     and tables you had, but with no data.  It will then physically move the
     data files containing non-system tables and indexes from
     <filename>data.old/</filename> into the proper
     <filename>data/</filename> subdirectories, replacing the empty data files
     created during the db.out script.
    </para>
   </step>

   <step performance="required">
    <para>
     Restore your old <filename>pg_hba.conf</filename> if needed to allow
     user logins.
    </para>
   </step>

   <step performance="required">
    <para>
     <emphasis>Carefully</emphasis> examine the contents of the upgraded
     databases.  If you detect problems, you'll need to recover by restoring
     from your full pg_dump backup.
     You can delete the <filename>data.old/</filename> directory when you
     are satisfied.
    </para>
   </step>

   <step performance="required">
    <para>
     The upgraded databases will be in an un-vacuumed state.  You will probably
     want to run a <command>VACUUM ANALYZE</command> before beginning
     production work.
    </para>
   </step>
  </procedure>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->
