Home • Explore • Blog • CI
☰



postgresql
5th chunk of `doc/src/sgml/ref/pgupgrade.sgml`
a3a0a00177302c68ad45c608f8fac3a458bf34934e30f2210000000100000fa3
 inherited values. There are two specific
        scenarios where this option is relevant:
        <itemizedlist>
         <listitem>
          <para>
           If you are planning to migrate to a different platform after the upgrade,
           you should not use this option. The default behavior is right in this case.
           Instead, perform the upgrade on the original platform without this flag,
           and then migrate the cluster afterward. This is the recommended and safest
           approach.
          </para>
         </listitem>
         <listitem>
          <para>
           If you have already migrated the cluster to a platform with different
           char signedness (for example, from an x86-based system to an ARM-based
           system), you should use this option to specify the signedness matching
           the original platform's default char signedness. Additionally, it's
           essential not to modify any data files between migrating data files and
           running <command>pg_upgrade</command>. <command>pg_upgrade</command>
           should be the first operation that starts the cluster on the new platform.
          </para>
         </listitem>
        </itemizedlist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--swap</option></term>
      <listitem>
       <para>
        Move the data directories from the old cluster to the new cluster.
        Then, replace the catalog files with those generated for the new
        cluster.  This mode can outperform <option>--link</option>,
        <option>--clone</option>, <option>--copy</option>, and
        <option>--copy-file-range</option>, especially on clusters with many
        relations.
       </para>
       <para>
        However, this mode creates many garbage files in the old cluster, which
        can prolong the file synchronization step if
        <option>--sync-method=syncfs</option> is used.  Therefore, it is
        recommended to use <option>--sync-method=fsync</option> with
        <option>--swap</option>.
       </para>
       <para>
        Additionally, once the file transfer step begins, the old cluster will
        be destructively modified and therefore will no longer be safe to
        start.  See <xref linkend="pgupgrade-step-revert"/> for details.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--sync-method=</option><replaceable>method</replaceable></term>
      <listitem>
       <para>
        When set to <literal>fsync</literal>, which is the default,
        <command>pg_upgrade</command> will recursively open and synchronize all
        files in the upgraded cluster's data directory.  The search for files
        will follow symbolic links for the WAL directory and each configured
        tablespace.
       </para>
       <para>
        On Linux, <literal>syncfs</literal> may be used instead to ask the
        operating system to synchronize the 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
Title: pg_upgrade Command Line Options (Continued): Char Signedness Scenarios, Data Directory Swapping, and Sync Method
Summary
This section details specific scenarios for using the `--set-char-signedness` option during `pg_upgrade`, particularly when migrating across platforms with different default `char` signedness. It also describes the `--swap` option, which involves moving data directories and replacing catalog files for potentially faster upgrades, along with its implications for the old cluster and the recommendation to use `--sync-method=fsync`. Finally, it covers the `--sync-method` option itself, allowing selection between `fsync` (the default) and `syncfs` for synchronizing the upgraded cluster's data. The section concludes with the standard help option and introduces the next section on general usage steps for `pg_upgrade`.