<varlistentry>
     <term><envar>PGPORTOLD</envar></term>

     <listitem>
      <para>
       The old cluster port number; option
       <option>-p</option>/<option>--old-port</option>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><envar>PGPORTNEW</envar></term>

     <listitem>
      <para>
       The new cluster port number; option
       <option>-P</option>/<option>--new-port</option>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><envar>PGSOCKETDIR</envar></term>

     <listitem>
      <para>
       Directory to use for postmaster sockets during upgrade; option
       <option>-s</option>/<option>--socketdir</option>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><envar>PGUSER</envar></term>

     <listitem>
      <para>
       Cluster's install user name; option
       <option>-U</option>/<option>--username</option>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   <application>pg_upgrade</application> creates various working files, such
   as schema dumps, stored within <filename>pg_upgrade_output.d</filename> in
   the directory of the new cluster. Each run creates a new subdirectory named
   with a timestamp formatted as per ISO 8601
   (<literal>%Y%m%dT%H%M%S</literal>), where all its generated files are
   stored.
   <filename>pg_upgrade_output.d</filename> and its contained files will be
   removed automatically if <application>pg_upgrade</application> completes
   successfully; but in the event of trouble, the files there may provide
   useful debugging information.
  </para>

  <para>
   <application>pg_upgrade</application> launches short-lived postmasters in
   the old and new data directories.  Temporary Unix socket files for
   communication with these postmasters are, by default, made in the current
   working directory.  In some situations the path name for the current
   directory might be too long to be a valid socket name.  In that case you
   can use the <option>-s</option> option to put the socket files in some
   directory with a shorter path name.  For security, be sure that that
   directory is not readable or writable by any other users.
   (This is not supported on Windows.)
  </para>

  <para>
   All failure, rebuild, and reindex cases will be reported by
   <application>pg_upgrade</application> if they affect your installation;
   post-upgrade scripts to rebuild tables and indexes will be
   generated