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> will report this and create
     a script that can be run later to update them.
    </para>
   </step>

   <step>
    <title>Copy custom full-text search files</title>

    <para>
     Copy any custom full text search files (dictionary, synonym,
     thesaurus, stop words) from the old to the new cluster.
    </para>
   </step>

   <step>
    <title>Adjust authentication</title>

    <para>
     <command>pg_upgrade</command> will connect to the old and new servers several
     times, so you might want to set authentication to <literal>peer</literal>
     in <filename>pg_hba.conf</filename> or use a <filename>~/.pgpass</filename> file
     (see <xref linkend="libpq-pgpass"/>).
    </para>
   </step>

   <step>
    <title>Stop both servers</title>

    <para>
     Make sure both database servers are stopped using, on Unix, e.g.:

<programlisting>
pg_ctl -D /opt/PostgreSQL/12 stop
pg_ctl -D /opt/PostgreSQL/&majorversion; stop
</programlisting>

     or on Windows, using the proper service names:

<programlisting>
NET STOP postgresql-12
NET STOP postgresql-&majorversion;
</programlisting>
    </para>

    <para>
     Streaming replication and log-shipping standby servers must be
     running during this shutdown so they receive all changes.
    </para>
   </step>

   <step>
    <title>Prepare for standby server upgrades</title>

    <para>
     If you are upgrading standby servers using methods outlined in section <xref
     linkend="pgupgrade-step-replicas"/>, verify that the old standby
     servers are caught up by running <application>pg_controldata</application>
     against the old primary and standby clusters.  Verify that the
     <quote>Latest checkpoint location</quote> values match in all clusters.
     Also, make sure <varname>wal_level</varname> is not set to
     <literal>minimal</literal> in the <filename>postgresql.conf</filename> file on the
     new primary cluster.
    </para>
   </step>

   <step>
    <title>Run <application>pg_upgrade</application></title>

    <para>
     Always run the <application>pg_upgrade</application> binary of the new server, not the old one.
     <application>pg_upgrade</application> requires the specification of the old and new cluster's
     data and executable (<filename>bin</filename>) directories. You can also specify
     user and port values, and whether you want the data files linked, cloned, or swapped
     instead of the default copy behavior.
    </para>

    <para>
     If you use link mode, the upgrade will be much faster (no file
     copying) and use less disk space, but you will not be able to access
     your old cluster
     once you start the new cluster after the upgrade.  Link mode also
     requires that the old and new cluster data directories be in the
     same file system.  (Tablespaces and <filename>pg_wal</filename> can be on
     different file systems.)
     Clone mode provides the same speed and disk space advantages but
     does not cause the old cluster to be unusable once