Home • Explore • Blog • CI
☰



postgresql
4th chunk of `doc/src/sgml/ref/pgupgrade.sgml`
a04a9c7ef3384e77bed7bcc4465dac593a0cd824c9a3786d0000000100000fa0
       leaving the old cluster untouched.
       </para>

       <para>
        File cloning is only supported on some operating systems and file
        systems.  If it is selected but not supported, the
        <application>pg_upgrade</application> run will error.  At present, it
        is supported on Linux (kernel 4.5 or later) with Btrfs and XFS (on
        file systems created with reflink support), and on macOS with APFS.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--copy</option></term>
      <listitem>
       <para>
        Copy files to the new cluster.  This is the default.  (See also
        <option>--link</option>, <option>--clone</option>,
        <option>--copy-file-range</option>, and <option>--swap</option>.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--copy-file-range</option></term>
      <listitem>
       <para>
        Use the <function>copy_file_range</function> system call for efficient
        copying.  On some file systems this gives results similar to
        <option>--clone</option>, sharing physical disk blocks, while on others
        it may still copy blocks, but do so via an optimized path.  At present,
        it is supported on Linux and FreeBSD.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--no-statistics</option></term>
      <listitem>
       <para>
        Do not restore statistics from the old cluster into the new cluster.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--set-char-signedness=</option><replaceable>option</replaceable></term>
      <listitem>
       <para>
        Manually set the default char signedness of new clusters. Possible values
        are <literal>signed</literal> and <literal>unsigned</literal>.
       </para>
       <para>
        In the C language, the default signedness of the <type>char</type> type
        (when not explicitly specified) varies across platforms. For example,
        <type>char</type> defaults to <type>signed char</type> on x86 CPUs but
        to <type>unsigned char</type> on ARM CPUs.
       </para>
       <para>
        Starting from <productname>PostgreSQL</productname> 18, database clusters
        maintain their own default char signedness setting, which can be used to
        ensure consistent behavior across platforms with different default char
        signedness. By default, <application>pg_upgrade</application> preserves
        the char signedness setting when upgrading from an existing cluster.
        However, when upgrading from <productname>PostgreSQL</productname> 17 or
        earlier, <application>pg_upgrade</application> adopts the char signedness
        of the platform on which it was built.
       </para>
       <para>
        This option allows you to explicitly set the default char signedness for
        the new cluster, overriding any 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
Title: pg_upgrade Command Line Options (Continued): File Copying, Statistics, and Char Signedness
Summary
This section continues the description of `pg_upgrade` command-line options. It explains the usage of `--copy-file-range` for efficient file copying using the `copy_file_range` system call. It also covers options for skipping statistics restoration (`--no-statistics`) and manually setting the default char signedness for new clusters (`--set-char-signedness`), which is particularly important for cross-platform upgrades due to variations in the default signedness of the `char` type in the C language.