PostgreSQL/doc/src/sgml/ref/pg_upgrade.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_upgrade.sgml,v 1.17 2002/01/11 06:08:02 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>
  <synopsis>
pg_upgrade -s <replaceable class="parameter">filename</replaceable> <replaceable class="parameter">old_data_dir</replaceable>
  </synopsis>
 </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>
     Then do:
     <programlisting>
$ pg_dumpall -s > schema.out
     </programlisting>
     to dump out your old database's table definitions without any data.
    </para>
   </step>

   <step performance="required">
    <para>
     <command>VACUUM</command> your entire database using
     <command>vacuumdb -a</command.>
    </para>
   </step>

   <step performance="required">
    <para>
     Stop the old postmaster and all backends.
    </para>
   </step>

   <step performance="required">
    <para>
     Rename (using mv) your old pgsql <filename>data/</filename> directory to
     <filename>data.old/</filename>.
    </para>
   </step>

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

   <step performance="required">
    <para>
     Run <application>initdb</application> to create a new template1 database
     containing the system tables for the new release.
    </para>
   </step>

   <step performance="required">
    <para>
     Start the new postmaster.  (Note: it is critical that no users connect
     to the database 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 -s schema.out data.old
     </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
     database.  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 database will be in an un-vacuumed state.  You will probably
     want to run a <command>VACUUM ANALYZE</command> before beginning
     production work.
    </para>
   </step>

   <note>
    <para>
     pg_upgrade does not migrate large objects.
    </para>
   </note>
  </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:
-->