<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 the new cluster
     is started.  Clone mode also requires that the old and new data
     directories be in the same file system.  This mode is only available
     on certain operating systems and file systems.
     Swap mode may be the fastest if there are many relations, but you will not
     be able to access your old cluster once the file transfer step begins.
     Swap mode also requires that the old and new cluster data directories be
     in the same file system.
    </para>

    <para>
     Setting <option>--jobs</option> to 2 or higher allows pg_upgrade to
     process multiple databases and tablespaces in parallel.  A good starting
     point is the number of CPU cores on the machine.  This option can
     substantially reduce the upgrade time for multi-database and
     multi-tablespace servers.
    </para>

    <para>
     For Windows users, you must be logged into an administrative account,
     and then run <application>pg_upgrade</application> with quoted
     directories, e.g.:

<programlisting>
pg_upgrade.exe
        --old-datadir "C:/Program Files/PostgreSQL/12/data"
        --new-datadir "C:/Program Files/PostgreSQL/&majorversion;/data"
        --old-bindir "C:/Program Files/PostgreSQL/12/bin"
        --new-bindir "C:/Program Files/PostgreSQL/&majorversion;/bin"
</programlisting>

     Once started, <command>pg_upgrade</command> will verify the two clusters are compatible
     and then do the upgrade. You can use <command>pg_upgrade --check</command>
     to perform only the checks, even if the old server is still
     running. <command>pg_upgrade --check</command> will also outline any
     manual adjustments you will need to make after the upgrade.  If you
     are going to be using link, clone, copy-file-range, or swap mode, you
     should use the option <option>--link</option>, <option>--clone</option>,
     <option>--copy-file-range</option>, or <option>--swap</option> with
     <option>--check</option> to enable mode-specific checks.
     <command>pg_upgrade</command> requires write permission in the current directory.
    </para>

    <para>
     Obviously, no one should be accessing the clusters during the
     upgrade.  <application>pg_upgrade</application> defaults to running servers
     on port 50432 to avoid unintended client connections.
     You can use the same port number for both clusters when doing an
     upgrade because the old and new clusters will not be running at the
     same time.  However, when checking an old running server, the old
     and new port numbers must be different.
    </para>

    <para>
     If an error occurs while restoring the database schema, <command>pg_upgrade</command> will
     exit and you will have to revert to the old cluster as outlined in <xref linkend="pgupgrade-step-revert"/>
     below. To try <command>pg_upgrade</command> again, you will need to modify the old
     cluster so the pg_upgrade schema restore succeeds. If the problem