open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: Put new options in consistent order on man pages

Browse Source
pull/221/head
Peter Eisentraut 4 months ago
parent b28c59a6cd
commit bc35adee8d
5 changed files with 294 additions and 294 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 58
      doc/src/sgml/ref/pg_combinebackup.sgml
  2. 94
      doc/src/sgml/ref/pg_resetwal.sgml
  3. 276
      doc/src/sgml/ref/pg_restore.sgml
  4. 58
      doc/src/sgml/ref/pg_verifybackup.sgml
  5. 102
      doc/src/sgml/ref/pgupgrade.sgml

58
doc/src/sgml/ref/pg_combinebackup.sgml
Unescape View File

@ -81,6 +81,35 @@ PostgreSQL documentation
</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>
@ -137,35 +166,6 @@ PostgreSQL documentation
</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>

94
doc/src/sgml/ref/pg_resetwal.sgml
Unescape View File

@ -171,25 +171,6 @@ PostgreSQL documentation
</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>
@ -332,34 +313,6 @@ PostgreSQL documentation
</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>
@ -402,6 +355,53 @@ PostgreSQL documentation
<!-- 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>

276
doc/src/sgml/ref/pg_restore.sgml
Unescape View File

@ -177,28 +177,6 @@ PostgreSQL documentation
</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>
@ -223,86 +201,6 @@ PostgreSQL documentation
</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>
@ -646,15 +544,6 @@ PostgreSQL documentation
</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>
@ -714,6 +603,108 @@ PostgreSQL documentation
</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>
@ -851,33 +842,6 @@ PostgreSQL documentation
</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>
@ -897,6 +861,15 @@ PostgreSQL documentation
</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>
@ -946,6 +919,33 @@ PostgreSQL documentation
</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>

58
doc/src/sgml/ref/pg_verifybackup.sgml
Unescape View File

@ -143,35 +143,6 @@ PostgreSQL documentation
</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>
@ -211,6 +182,35 @@ PostgreSQL documentation
</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>

102
doc/src/sgml/ref/pgupgrade.sgml
Unescape View File

@ -145,15 +145,6 @@ PostgreSQL documentation
</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>
@ -264,50 +255,10 @@ PostgreSQL documentation
</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>
@ -365,6 +316,55 @@ PostgreSQL documentation
</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>

Write Preview
Loading…
Cancel
Save