whole file systems that contain the
        upgraded cluster's data directory, its WAL files, and each tablespace.
        See <xref linkend="guc-recovery-init-sync-method"/> for information
        about the caveats to be aware of when using <literal>syncfs</literal>.
       </para>
       <para>
        This option has no effect when <option>--no-sync</option> is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-?</option></term>
      <term><option>--help</option></term>
      <listitem><para>show help, then exit</para></listitem>
     </varlistentry>

    </variablelist>
   </para>

 </refsect1>

 <refsect1>
  <title>Usage</title>

  <para>
   These are the steps to perform an upgrade
   with <application>pg_upgrade</application>:
  </para>

   <note>
    <para>
     The steps to upgrade <glossterm linkend="glossary-logical-replication-cluster">logical replication clusters</glossterm>
     are not covered here;
     refer to <xref linkend="logical-replication-upgrade"/> for details.
    </para>
   </note>

  <procedure>
   <step performance="optional">
    <title>Optionally move the old cluster</title>

    <para>
     If you are using a version-specific installation directory, e.g.,
     <filename>/opt/PostgreSQL/&majorversion;</filename>, you do not need to move the old cluster. The
     graphical installers all use version-specific installation directories.
    </para>

    <para>
     If your installation directory is not version-specific, e.g.,
     <filename>/usr/local/pgsql</filename>, it is necessary to move the current PostgreSQL install
     directory so it does not interfere with the new <productname>PostgreSQL</productname> installation.
     Once the current <productname>PostgreSQL</productname> server is shut down, it is safe to rename the
     PostgreSQL installation directory; assuming the old directory is
     <filename>/usr/local/pgsql</filename>, you can do:

<programlisting>
mv /usr/local/pgsql /usr/local/pgsql.old
</programlisting>
     to rename the directory.
    </para>
   </step>

   <step>
    <title>For source installs, build the new version</title>

    <para>
     Build the new PostgreSQL source with <command>configure</command> flags that are compatible
     with the old cluster. <application>pg_upgrade</application> will check <command>pg_controldata</command> to make
     sure all settings are compatible before starting the upgrade.
    </para>
   </step>

   <step>
    <title>Install the new PostgreSQL binaries</title>

    <para>
     Install the new server's binaries and support
     files.  <application>pg_upgrade</application> is included in a default installation.
    </para>

    <para>
     For source installs, if you wish to install the new server in a custom
     location, use the <literal>prefix</literal> variable:

<programlisting>
make prefix=/usr/local/pgsql.new install
</programlisting></para>
   </step>

   <step>
    <title>Initialize the new PostgreSQL cluster</title>

    <para>
     Initialize the new cluster using <command>initdb</command>.
     Again, use compatible <command>initdb</command>
     flags that match the old cluster. Many
     prebuilt installers do this step automatically. There is no need to
     start the new cluster.
    </para>
   </step>

   <step>
    <title>Install extension shared object files</title>

    <para>
     Many extensions and custom modules, whether from
     <filename>contrib</filename> or another source, use shared object
     files (or DLLs), e.g., <filename>pgcrypto.so</filename>.  If the old
     cluster used these, shared object files matching the new server binary
     must be installed in the new cluster, usually via operating system
     commands.  Do not load the schema definitions, e.g., <command>CREATE
     EXTENSION pgcrypto</command>, because these will be duplicated from
     the old cluster.  If extension updates are available,
     <application>pg_upgrade</application>