From: Peter Eisentraut Date: Fri, 9 May 2025 06:55:05 +0000 (+0200) Subject: doc: Put new options in consistent order on man pages X-Git-Url: http://git.postgresql.org/gitweb/?a=commitdiff_plain;h=bc35adee8d7ad38e7bef40052f196be55decddec;p=postgresql.git doc: Put new options in consistent order on man pages --- diff --git a/doc/src/sgml/ref/pg_combinebackup.sgml b/doc/src/sgml/ref/pg_combinebackup.sgml index 55bc46849db..330a598f701 100644 --- a/doc/src/sgml/ref/pg_combinebackup.sgml +++ b/doc/src/sgml/ref/pg_combinebackup.sgml @@ -81,6 +81,35 @@ PostgreSQL documentation + + + + + + 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 pg_combinebackup has completed. + + + + Requires that the input backups and the output directory are in the + same file system. + + + + 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. + + + + @@ -137,35 +166,6 @@ PostgreSQL documentation - - - - - - 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 pg_combinebackup has completed. - - - - Requires that the input backups and the output directory are in the - same file system. - - - - 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. - - - - diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml index dd011d246c1..2c019c2aac6 100644 --- a/doc/src/sgml/ref/pg_resetwal.sgml +++ b/doc/src/sgml/ref/pg_resetwal.sgml @@ -171,25 +171,6 @@ PostgreSQL documentation - - - - - Manually set the default char signedness. Possible values are - signed and unsigned. - - - For a database cluster that pg_upgrade upgraded from - a PostgreSQL version before 18, the safe - value would be the default char signedness of the platform - that ran the cluster before that upgrade. For all other - clusters, signed would be the safe value. However, - this option is exclusively for use with pg_upgrade - and should not normally be used manually. - - - - @@ -332,34 +313,6 @@ PostgreSQL documentation - - - - - 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 for more information. - - - - This option can also be used to change the WAL segment size of an - existing database cluster, avoiding the need to - re-initdb. - - - - - While pg_resetwal 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 together with this option to manually set the - WAL starting address if WAL file name overlap will cause problems with - your archiving strategy. - - - - - @@ -402,6 +355,53 @@ PostgreSQL documentation + + + + + + Manually set the default char signedness. Possible values are + signed and unsigned. + + + For a database cluster that pg_upgrade upgraded from + a PostgreSQL version before 18, the safe + value would be the default char signedness of the platform + that ran the cluster before that upgrade. For all other + clusters, signed would be the safe value. However, + this option is exclusively for use with pg_upgrade + and should not normally be used manually. + + + + + + + + + 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 for more information. + + + + This option can also be used to change the WAL segment size of an + existing database cluster, avoiding the need to + re-initdb. + + + + + While pg_resetwal 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 together with this option to manually set the + WAL starting address if WAL file name overlap will cause problems with + your archiving strategy. + + + + diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index b6de497aee1..2295df62d03 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -177,28 +177,6 @@ PostgreSQL documentation - - - - - Do not restore databases whose name matches - pattern. - Multiple patterns can be excluded by writing multiple - switches. The - pattern parameter is - interpreted as a pattern according to the same rules used by - psql's \d - commands (see ), - 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. - - - This option is only relevant when restoring from an archive made using pg_dumpall. - - - - @@ -223,86 +201,6 @@ PostgreSQL documentation - - - - - 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 - / for including objects in schemas, - / for excluding objects in schemas, - / for restoring named functions, - / for restoring named indexes, - / for restoring named tables - or / for restoring triggers. - To read from STDIN, use - as the - filename. The 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. - - - - The file lists one database pattern per row, with the following format: - -{ include | exclude } { function | index | schema | table | trigger } PATTERN - - - - - 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: - - - - function: functions, works like the - / option. This keyword - can only be used with the include keyword. - - - - - index: indexes, works like the - / option. This keyword - can only be used with the include keyword. - - - - - schema: schemas, works like the - / and - / options. - - - - - table: tables, works like the - / option. This keyword - can only be used with the include keyword. - - - - - trigger: triggers, works like the - / option. This keyword - can only be used with the include keyword. - - - - - - - Lines starting with # are considered comments and - ignored. Comments can be placed after an object pattern row as well. - Blank lines are also ignored. See - for how to perform quoting in patterns. - - - - - @@ -646,15 +544,6 @@ PostgreSQL documentation - - - - - Restore only the statistics, not schema (data definitions) or data. - - - - @@ -714,6 +603,108 @@ PostgreSQL documentation + + + + + Do not restore databases whose name matches + pattern. + Multiple patterns can be excluded by writing multiple + switches. The + pattern parameter is + interpreted as a pattern according to the same rules used by + psql's \d + commands (see ), + 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. + + + This option is only relevant when restoring from an archive made using pg_dumpall. + + + + + + + + + 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 + / for including objects in schemas, + / for excluding objects in schemas, + / for restoring named functions, + / for restoring named indexes, + / for restoring named tables + or / for restoring triggers. + To read from STDIN, use - as the + filename. The 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. + + + + The file lists one database pattern per row, with the following format: + +{ include | exclude } { function | index | schema | table | trigger } PATTERN + + + + + 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: + + + + function: functions, works like the + / option. This keyword + can only be used with the include keyword. + + + + + index: indexes, works like the + / option. This keyword + can only be used with the include keyword. + + + + + schema: schemas, works like the + / and + / options. + + + + + table: tables, works like the + / option. This keyword + can only be used with the include keyword. + + + + + trigger: triggers, works like the + / option. This keyword + can only be used with the include keyword. + + + + + + + Lines starting with # are considered comments and + ignored. Comments can be placed after an object pattern row as well. + Blank lines are also ignored. See + for how to perform quoting in patterns. + + + + + @@ -851,33 +842,6 @@ PostgreSQL documentation - - - - - Dump data. This is the default. - - - - - - - - - Dump schema (data definitions). This is the default. - - - - - - - - - Dump statistics. This is the default. - - - - @@ -897,6 +861,15 @@ PostgreSQL documentation + + + + + Restore only the statistics, not schema (data definitions) or data. + + + + @@ -946,6 +919,33 @@ PostgreSQL documentation + + + + + Dump data. This is the default. + + + + + + + + + Dump schema (data definitions). This is the default. + + + + + + + + + Dump statistics. This is the default. + + + + diff --git a/doc/src/sgml/ref/pg_verifybackup.sgml b/doc/src/sgml/ref/pg_verifybackup.sgml index 53341024cd2..61c12975e4a 100644 --- a/doc/src/sgml/ref/pg_verifybackup.sgml +++ b/doc/src/sgml/ref/pg_verifybackup.sgml @@ -143,35 +143,6 @@ PostgreSQL documentation - - - - - - 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 - backup_manifest 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. - - - - - - - - - - Use the manifest file at the specified path, rather than one located - in the root of the backup directory. - - - - @@ -211,6 +182,35 @@ PostgreSQL documentation + + + + + + 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 + backup_manifest 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. + + + + + + + + + + Use the manifest file at the specified path, rather than one located + in the root of the backup directory. + + + + diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index cb8e4f5c48a..aeeed297437 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -145,15 +145,6 @@ PostgreSQL documentation - - - - - Do not restore statistics from the old cluster into the new cluster. - - - - options options @@ -264,50 +255,10 @@ PostgreSQL documentation - - - - 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 , - , , and - , especially on clusters with many - relations. - - - However, this mode creates many garbage files in the old cluster, which - can prolong the file synchronization step if - is used. Therefore, it is - recommended to use with - . - - - Additionally, once the file transfer step begins, the old cluster will - be destructively modified and therefore will no longer be safe to - start. See for details. - - - - - - method + - When set to fsync, which is the default, - pg_upgrade 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. - - - On Linux, syncfs 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 for information - about the caveats to be aware of when using syncfs. - - - This option has no effect when is used. + Do not restore statistics from the old cluster into the new cluster. @@ -365,6 +316,55 @@ PostgreSQL documentation + + + + + 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 , + , , and + , especially on clusters with many + relations. + + + However, this mode creates many garbage files in the old cluster, which + can prolong the file synchronization step if + is used. Therefore, it is + recommended to use with + . + + + Additionally, once the file transfer step begins, the old cluster will + be destructively modified and therefore will no longer be safe to + start. See for details. + + + + + + method + + + When set to fsync, which is the default, + pg_upgrade 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. + + + On Linux, syncfs 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 for information + about the caveats to be aware of when using syncfs. + + + This option has no effect when is used. + + + +