</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-k</option></term>
+ <term><option>--link</option></term>
+ <listitem>
+ <para>
+ Use hard links instead of copying files to the synthetic backup.
+ Reconstruction of the synthetic backup might be faster (no file copying)
+ and use less disk space, but care must be taken when using the output
+ directory, because any modifications to that directory (for example,
+ starting the server) can also affect the input directories. Likewise,
+ changes to the input directories (for example, starting the server on
+ the full backup) could affect the output directory. Thus, this option
+ is best used when the input directories are only copies that will be
+ removed after <application>pg_combinebackup</application> has completed.
+ </para>
+
+ <para>
+ Requires that the input backups and the output directory are in the
+ same file system.
+ </para>
+
+ <para>
+ If a backup manifest is not available or does not contain checksum of
+ the right type, hard links will still be created, but the file will be
+ also read block-by-block for the checksum calculation.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>-n</option></term>
<term><option>--dry-run</option></term>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>-k</option></term>
- <term><option>--link</option></term>
- <listitem>
- <para>
- Use hard links instead of copying files to the synthetic backup.
- Reconstruction of the synthetic backup might be faster (no file copying)
- and use less disk space, but care must be taken when using the output
- directory, because any modifications to that directory (for example,
- starting the server) can also affect the input directories. Likewise,
- changes to the input directories (for example, starting the server on
- the full backup) could affect the output directory. Thus, this option
- is best used when the input directories are only copies that will be
- removed after <application>pg_combinebackup</application> has completed.
- </para>
-
- <para>
- Requires that the input backups and the output directory are in the
- same file system.
- </para>
-
- <para>
- If a backup manifest is not available or does not contain checksum of
- the right type, hard links will still be created, but the file will be
- also read block-by-block for the checksum calculation.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--clone</option></term>
<listitem>
</para>
<variablelist>
- <varlistentry>
- <term><option>--char-signedness=<replaceable class="parameter">option</replaceable></option></term>
- <listitem>
- <para>
- Manually set the default char signedness. Possible values are
- <literal>signed</literal> and <literal>unsigned</literal>.
- </para>
- <para>
- For a database cluster that <command>pg_upgrade</command> upgraded from
- a <productname>PostgreSQL</productname> version before 18, the safe
- value would be the default <type>char</type> signedness of the platform
- that ran the cluster before that upgrade. For all other
- clusters, <literal>signed</literal> would be the safe value. However,
- this option is exclusively for use with <command>pg_upgrade</command>
- and should not normally be used manually.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-c <replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></option></term>
<term><option>--commit-timestamp-ids=<replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></option></term>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--wal-segsize=<replaceable class="parameter">wal_segment_size</replaceable></option></term>
- <listitem>
- <para>
- Set the new WAL segment size, in megabytes. The value must be set to a
- power of 2 between 1 and 1024 (megabytes). See the same option of <xref
- linkend="app-initdb"/> for more information.
- </para>
-
- <para>
- This option can also be used to change the WAL segment size of an
- existing database cluster, avoiding the need to
- re-<command>initdb</command>.
- </para>
-
- <note>
- <para>
- While <command>pg_resetwal</command> will set the WAL starting address
- beyond the latest existing WAL segment file, some segment size changes
- can cause previous WAL file names to be reused. It is recommended to
- use <option>-l</option> together with this option to manually set the
- WAL starting address if WAL file name overlap will cause problems with
- your archiving strategy.
- </para>
- </note>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-u <replaceable class="parameter">xid</replaceable></option></term>
<term><option>--oldest-transaction-id=<replaceable class="parameter">xid</replaceable></option></term>
<!-- 1048576 = SLRU_PAGES_PER_SEGMENT * BLCKSZ * CLOG_XACTS_PER_BYTE -->
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>--char-signedness=<replaceable class="parameter">option</replaceable></option></term>
+ <listitem>
+ <para>
+ Manually set the default char signedness. Possible values are
+ <literal>signed</literal> and <literal>unsigned</literal>.
+ </para>
+ <para>
+ For a database cluster that <command>pg_upgrade</command> upgraded from
+ a <productname>PostgreSQL</productname> version before 18, the safe
+ value would be the default <type>char</type> signedness of the platform
+ that ran the cluster before that upgrade. For all other
+ clusters, <literal>signed</literal> would be the safe value. However,
+ this option is exclusively for use with <command>pg_upgrade</command>
+ and should not normally be used manually.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--wal-segsize=<replaceable class="parameter">wal_segment_size</replaceable></option></term>
+ <listitem>
+ <para>
+ Set the new WAL segment size, in megabytes. The value must be set to a
+ power of 2 between 1 and 1024 (megabytes). See the same option of <xref
+ linkend="app-initdb"/> for more information.
+ </para>
+
+ <para>
+ This option can also be used to change the WAL segment size of an
+ existing database cluster, avoiding the need to
+ re-<command>initdb</command>.
+ </para>
+
+ <note>
+ <para>
+ While <command>pg_resetwal</command> will set the WAL starting address
+ beyond the latest existing WAL segment file, some segment size changes
+ can cause previous WAL file names to be reused. It is recommended to
+ use <option>-l</option> together with this option to manually set the
+ WAL starting address if WAL file name overlap will cause problems with
+ your archiving strategy.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--exclude-database=<replaceable class="parameter">pattern</replaceable></option></term>
- <listitem>
- <para>
- Do not restore databases whose name matches
- <replaceable class="parameter">pattern</replaceable>.
- Multiple patterns can be excluded by writing multiple
- <option>--exclude-database</option> switches. The
- <replaceable class="parameter">pattern</replaceable> parameter is
- interpreted as a pattern according to the same rules used by
- <application>psql</application>'s <literal>\d</literal>
- commands (see <xref linkend="app-psql-patterns"/>),
- so multiple databases can also be excluded by writing wildcard
- characters in the pattern. When using wildcards, be careful to
- quote the pattern if needed to prevent shell wildcard expansion.
- </para>
- <para>
- This option is only relevant when restoring from an archive made using <application>pg_dumpall</application>.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-e</option></term>
<term><option>--exit-on-error</option></term>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--filter=<replaceable class="parameter">filename</replaceable></option></term>
- <listitem>
- <para>
- Specify a filename from which to read patterns for objects excluded
- or included from restore. The patterns are interpreted according to the
- same rules as
- <option>-n</option>/<option>--schema</option> for including objects in schemas,
- <option>-N</option>/<option>--exclude-schema</option> for excluding objects in schemas,
- <option>-P</option>/<option>--function</option> for restoring named functions,
- <option>-I</option>/<option>--index</option> for restoring named indexes,
- <option>-t</option>/<option>--table</option> for restoring named tables
- or <option>-T</option>/<option>--trigger</option> for restoring triggers.
- To read from <literal>STDIN</literal>, use <filename>-</filename> as the
- filename. The <option>--filter</option> option can be specified in
- conjunction with the above listed options for including or excluding
- objects, and can also be specified more than once for multiple filter
- files.
- </para>
-
- <para>
- The file lists one database pattern per row, with the following format:
-<synopsis>
-{ include | exclude } { function | index | schema | table | trigger } <replaceable class="parameter">PATTERN</replaceable>
-</synopsis>
- </para>
-
- <para>
- The first keyword specifies whether the objects matched by the pattern
- are to be included or excluded. The second keyword specifies the type
- of object to be filtered using the pattern:
- <itemizedlist>
- <listitem>
- <para>
- <literal>function</literal>: functions, works like the
- <option>-P</option>/<option>--function</option> option. This keyword
- can only be used with the <literal>include</literal> keyword.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>index</literal>: indexes, works like the
- <option>-I</option>/<option>--indexes</option> option. This keyword
- can only be used with the <literal>include</literal> keyword.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>schema</literal>: schemas, works like the
- <option>-n</option>/<option>--schema</option> and
- <option>-N</option>/<option>--exclude-schema</option> options.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>table</literal>: tables, works like the
- <option>-t</option>/<option>--table</option> option. This keyword
- can only be used with the <literal>include</literal> keyword.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>trigger</literal>: triggers, works like the
- <option>-T</option>/<option>--trigger</option> option. This keyword
- can only be used with the <literal>include</literal> keyword.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- Lines starting with <literal>#</literal> are considered comments and
- ignored. Comments can be placed after an object pattern row as well.
- Blank lines are also ignored. See <xref linkend="app-psql-patterns"/>
- for how to perform quoting in patterns.
- </para>
-
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-F <replaceable class="parameter">format</replaceable></option></term>
<term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--statistics-only</option></term>
- <listitem>
- <para>
- Restore only the statistics, not schema (data definitions) or data.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-1</option></term>
<term><option>--single-transaction</option></term>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--exclude-database=<replaceable class="parameter">pattern</replaceable></option></term>
+ <listitem>
+ <para>
+ Do not restore databases whose name matches
+ <replaceable class="parameter">pattern</replaceable>.
+ Multiple patterns can be excluded by writing multiple
+ <option>--exclude-database</option> switches. The
+ <replaceable class="parameter">pattern</replaceable> parameter is
+ interpreted as a pattern according to the same rules used by
+ <application>psql</application>'s <literal>\d</literal>
+ commands (see <xref linkend="app-psql-patterns"/>),
+ so multiple databases can also be excluded by writing wildcard
+ characters in the pattern. When using wildcards, be careful to
+ quote the pattern if needed to prevent shell wildcard expansion.
+ </para>
+ <para>
+ This option is only relevant when restoring from an archive made using <application>pg_dumpall</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--filter=<replaceable class="parameter">filename</replaceable></option></term>
+ <listitem>
+ <para>
+ Specify a filename from which to read patterns for objects excluded
+ or included from restore. The patterns are interpreted according to the
+ same rules as
+ <option>-n</option>/<option>--schema</option> for including objects in schemas,
+ <option>-N</option>/<option>--exclude-schema</option> for excluding objects in schemas,
+ <option>-P</option>/<option>--function</option> for restoring named functions,
+ <option>-I</option>/<option>--index</option> for restoring named indexes,
+ <option>-t</option>/<option>--table</option> for restoring named tables
+ or <option>-T</option>/<option>--trigger</option> for restoring triggers.
+ To read from <literal>STDIN</literal>, use <filename>-</filename> as the
+ filename. The <option>--filter</option> option can be specified in
+ conjunction with the above listed options for including or excluding
+ objects, and can also be specified more than once for multiple filter
+ files.
+ </para>
+
+ <para>
+ The file lists one database pattern per row, with the following format:
+<synopsis>
+{ include | exclude } { function | index | schema | table | trigger } <replaceable class="parameter">PATTERN</replaceable>
+</synopsis>
+ </para>
+
+ <para>
+ The first keyword specifies whether the objects matched by the pattern
+ are to be included or excluded. The second keyword specifies the type
+ of object to be filtered using the pattern:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>function</literal>: functions, works like the
+ <option>-P</option>/<option>--function</option> option. This keyword
+ can only be used with the <literal>include</literal> keyword.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>index</literal>: indexes, works like the
+ <option>-I</option>/<option>--indexes</option> option. This keyword
+ can only be used with the <literal>include</literal> keyword.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>schema</literal>: schemas, works like the
+ <option>-n</option>/<option>--schema</option> and
+ <option>-N</option>/<option>--exclude-schema</option> options.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>table</literal>: tables, works like the
+ <option>-t</option>/<option>--table</option> option. This keyword
+ can only be used with the <literal>include</literal> keyword.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>trigger</literal>: triggers, works like the
+ <option>-T</option>/<option>--trigger</option> option. This keyword
+ can only be used with the <literal>include</literal> keyword.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Lines starting with <literal>#</literal> are considered comments and
+ ignored. Comments can be placed after an object pattern row as well.
+ Blank lines are also ignored. See <xref linkend="app-psql-patterns"/>
+ for how to perform quoting in patterns.
+ </para>
+
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--if-exists</option></term>
<listitem>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--with-data</option></term>
- <listitem>
- <para>
- Dump data. This is the default.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-schema</option></term>
- <listitem>
- <para>
- Dump schema (data definitions). This is the default.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-statistics</option></term>
- <listitem>
- <para>
- Dump statistics. This is the default.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--section=<replaceable class="parameter">sectionname</replaceable></option></term>
<listitem>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--statistics-only</option></term>
+ <listitem>
+ <para>
+ Restore only the statistics, not schema (data definitions) or data.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--strict-names</option></term>
<listitem>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--with-data</option></term>
+ <listitem>
+ <para>
+ Dump data. This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--with-schema</option></term>
+ <listitem>
+ <para>
+ Dump schema (data definitions). This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--with-statistics</option></term>
+ <listitem>
+ <para>
+ Dump statistics. This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>-?</option></term>
<term><option>--help</option></term>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>-i <replaceable class="parameter">path</replaceable></option></term>
- <term><option>--ignore=<replaceable class="parameter">path</replaceable></option></term>
- <listitem>
- <para>
- Ignore the specified file or directory, which should be expressed
- as a relative path name, when comparing the list of data files
- actually present in the backup to those listed in the
- <literal>backup_manifest</literal> file. If a directory is
- specified, this option affects the entire subtree rooted at that
- location. Complaints about extra files, missing files, file size
- differences, or checksum mismatches will be suppressed if the
- relative path name matches the specified path name. This option
- can be specified multiple times.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-m <replaceable class="parameter">path</replaceable></option></term>
- <term><option>--manifest-path=<replaceable class="parameter">path</replaceable></option></term>
- <listitem>
- <para>
- Use the manifest file at the specified path, rather than one located
- in the root of the backup directory.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-F <replaceable class="parameter">format</replaceable></option></term>
<term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-i <replaceable class="parameter">path</replaceable></option></term>
+ <term><option>--ignore=<replaceable class="parameter">path</replaceable></option></term>
+ <listitem>
+ <para>
+ Ignore the specified file or directory, which should be expressed
+ as a relative path name, when comparing the list of data files
+ actually present in the backup to those listed in the
+ <literal>backup_manifest</literal> file. If a directory is
+ specified, this option affects the entire subtree rooted at that
+ location. Complaints about extra files, missing files, file size
+ differences, or checksum mismatches will be suppressed if the
+ relative path name matches the specified path name. This option
+ can be specified multiple times.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-m <replaceable class="parameter">path</replaceable></option></term>
+ <term><option>--manifest-path=<replaceable class="parameter">path</replaceable></option></term>
+ <listitem>
+ <para>
+ Use the manifest file at the specified path, rather than one located
+ in the root of the backup directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>-n</option></term>
<term><option>--no-parse-wal</option></term>
</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>-o</option> <replaceable class="parameter">options</replaceable></term>
<term><option>--old-options</option> <replaceable class="parameter">options</replaceable></term>
</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>
+ <term><option>--no-statistics</option></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.
+ Do not restore statistics from the old cluster into the new cluster.
</para>
</listitem>
</varlistentry>
</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>
projects / postgresql.git / commitdiff