<!--
doc/src/sgml/ref/pgupgrade.sgml
PostgreSQL documentation
-->

<refentry id="pgupgrade">
 <indexterm zone="pgupgrade">
  <primary>pg_upgrade</primary>
 </indexterm>

 <refmeta>
  <refentrytitle><application>pg_upgrade</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_upgrade</refname>
  <refpurpose>upgrade a <productname>PostgreSQL</productname> server instance</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_upgrade</command>
   <arg choice="plain"><option>-b</option></arg>
   <arg choice="plain"><replaceable>oldbindir</replaceable></arg>
   <arg choice="opt"><option>-B</option> <replaceable>newbindir</replaceable></arg>
   <arg choice="plain"><option>-d</option></arg>
   <arg choice="plain"><replaceable>oldconfigdir</replaceable></arg>
   <arg choice="plain"><option>-D</option></arg>
   <arg choice="plain"><replaceable>newconfigdir</replaceable></arg>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

 <para>
  <application>pg_upgrade</application> (formerly called <application>pg_migrator</application>) allows data
  stored in <productname>PostgreSQL</productname> data files to be upgraded to a later <productname>PostgreSQL</productname>
  major version without the data dump/restore typically required for
  major version upgrades, e.g., from 12.14 to 13.10 or from 14.9 to 15.5.
  It is not required for minor version upgrades, e.g., from 12.7 to 12.8
  or from 14.1 to 14.5.
 </para>

 <para>
  Major PostgreSQL releases regularly add new features that often
  change the layout of the system tables, but the internal data storage
  format rarely changes.  <application>pg_upgrade</application> uses this fact
  to perform rapid upgrades by creating new system tables and simply
  reusing the old user data files.  If a future major release ever
  changes the data storage format in a way that makes the old data
  format unreadable, <application>pg_upgrade</application> will not be usable
  for such upgrades.  (The community will attempt to avoid such
  situations.)
 </para>

 <para>
  <application>pg_upgrade</application> does its best to
  make sure the old and new clusters are binary-compatible, e.g.,  by
  checking for compatible compile-time settings, including 32/64-bit
  binaries.  It is important that
  any external modules are also binary compatible, though this cannot
  be checked by <application>pg_upgrade</application>.
 </para>

  <para>
   <application>pg_upgrade</application> supports upgrades from 9.2.X and later to the current
   major release of <productname>PostgreSQL</productname>, including snapshot and beta releases.
  </para>
 </refsect1>

 <refsect1>
  <title>Options</title>

   <para>
    <application>pg_upgrade</application> accepts the following command-line arguments:

    <variablelist>

     <varlistentry>
      <term><option>-b</option> <replaceable>bindir</replaceable></term>
      <term><option>--old-bindir=</option><replaceable>bindir</replaceable></term>
      <listitem><para>the old PostgreSQL executable directory;
      environment variable <envar>PGBINOLD</envar></para></listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-B</option> <replaceable>bindir</replaceable></term>
      <term><option>--new-bindir=</option><replaceable>bindir</replaceable></term>
      <listitem><para>the new PostgreSQL executable directory;
      default is the directory where <application>pg_upgrade</application> resides;
      environment variable <envar>PGBINNEW</envar></para></listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-c</option></term>
      <term><option>--check</option></term>
      <listitem><para>check clusters only, don't change any data</para></listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-d</option> <replaceable>configdir</replaceable></term>